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Section 1 
OVERVIEW 



!•! Introduction 

The purpose of this COBOL-80 User's Guide is to give you practical information about 
getting a COBOL-80 program up and running on your computing equipment. All the steps 
necessary to use CGBOL-80 successfully — compiling, loading, executing, etc. — are 
carefully described in the following pages. 

In this guide, examples and file names are given which are based on a CP/M version of 
COBOL-80. If you are using another operating system, the format of commands and 
filenames will be slightly different. See Appendix D for a description of how COBOL is 
used with your operating system. 



1.2 Your Distribution Disk 

The disk you receive from Microsoft contains the following files: 

The COBOL Compiler 
C0B0L.COM 
COBOLl.OVR 
C0B0L2.0VR 
COBOL3.0VR 
COBOL4.0VR 

The Runtime System 

COBLIB.REL — the runtime library 

CRT Drivers — file whose names begin with CD 

Source - CD .MAC 

Object - CD_^.REL, CRTDRV.REL 

Utility Software 

L80.COM — the Microsoft Linking Loader 

LIB.COM — the Microsoft Library Manager 

M80.COM — the Microsoft Macro Assembler 

CREF80.COM — the Microsoft Assembly Cross-Reference Program 

Miscellaneous Files 

SQUARO.COB 
CRTEST.COB 
SEQCVT.COM 
COPCOB.SUB 
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1.2.1 The COBOL Compiler 

The compiler consists of a main program and four overlays. These five parts correspond 
to the five "phases" of compilation. The main program is always memory-resident and 
controls the transition from each phase to the next. The overlay portion of the main 
program compiles the IDENTIFICATION and ENVIRONMENT DIVISIONS. Overlay 1 is 
brought in to compile the DATA DIVISION. The PROCEDURE DIVISION is compiled by 
overlay 2. These 3 parts constitute the first pass of compilation. Their function is to 
create an intermediate version of the program, which is stored on the current disk in a 
file named STEXT.INT. Overlay 3 reads the intermediate file and creates the object 
code. Finally, overlay 4 allocates the file control blocks and checks certain error 
conditions. The intermediate file is then deleted. 



1.2.2 The Runtime System 

The runtime library consists of a group of subroutines that interpret the object code of 
your program produced by the compiler. These subroutines will be included with your 
object program when you perform the loading step. (See section 3 of this guide). Not ail 
programs will require all of the library routines. The loader will search the library and 
automatically include the portions you need and exclude the ones you don't. The CRT 
drivers are provided to enable you to configure your system for the type of CRT terminal 
you have. You will need to select the appropriate driver. (See Appendix A of this guide). 
Once you have done so, that driver will be automatically included with each program you 
load with the linking loader. The driver provides cursor positioning and other functions to 
support interactive ACCEPT and DISPLAY statements. 

1.2.3 Utility Software 

The Microsoft linking loader is used to link COBOL object programs with the runtime 
system. (See section 3 of this guide). The other utilities are provided for your 
convenience. Each of these programs is documented in the Microsoft Utility Software 
Manual. 

1.2.4 Miscellaneous Files 

SQUARO.COB is a COBOL source program that computes the square root of the number 
you provide. It is used to verify that you have a working version of the compiler and 
runtime system. 

CRTEST.COB is a COBOL source program that tests the functions of the interactive CRT 
driver (see Appendix A). 

SEQCVT.COM is a special utility program that converts COBOL files from LINE 
SEQUENTIAL format to SEQUENTIAL format. The COBOL-80 SEQUENTIAL file format 
was changed when version 3.0 was released. SEQUENTIAL organization files created by 
earlier versions are in the format that is now known as LINE SEQUENTIAL. 

COPCOB.SUB is a command file that copies the files on your distribution disk to a second 
disk. It is provided as a convenience. 
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1.3 Getting Started 

The first thing you should do when you receive your disk is to make a copy to use and save 
the original disk as a backup. This may be done by using the CGPCOB command file 
supplied or with some other disk copying facility you may have. 

Having done that, you should verify your copy of the compiler and runtime system by 
compiling, loading, and executing the test program SQUARO.COB. To do this, refer to 
the examples given below in section 1.4. 

Finally, if you intend to use the interactive ACCEPT and DISPLAY facility in your 
COBOL program, you must select a CRT driver and configure it into your runtime 
system. This procedure need be done only once; thereafter your selected driver will 
automatically be included with each of your object programs. See Appendix A of this 
guide for full instructions.' 



1.4 Program Development Steps 

Preparation of a COBOL program for execution consists of three basic steps: 

1. Creating the source file with a text editor 

2. Compiling with the COBOL Compiler 

3. Loading with the Linking Loader 

The source program is a file which consists of lines of ASCII text terminated by 
carriage-return line-feed. You can create it with Microsoft's EDIT-80 or any other editor 
that uses 7-bit ASCII character codes. Line numbers may be included in columns 1-6 of 
each line and these may be 8-bit ASCII codes. The compiler ignores characters other than 
TAB and carriage return until column 7 is reached. TAB stops assumed by the compiler 
are at columns 7, 17, 25, 33, 41, 49, 57, 65, and 73. All characters beyond column 73 are 
ignored until a CR is encountered. If you use EDIT-80, you automatically begin typing in 
column 7 of each inserted line. 

Having created the source program file, the next step is to compile it. This is done by 
typing a command line that will execute the COBOL compiler and provide the name of 
your source file. Under CP/M, you must be logged-in on the disk that contains the 
COBOL compiler, since the compiler overlays are always read from the current disk. The 
following example shows a command to compile the test program SQUARO which is 
included on your distribution disk, assuming drive A contains a copy of that disk. 

A> COBOL SQUARO.REL,TTY:=SQUARO.COB 

This command will compile SQUARO. COB, placing the relocatable object code in a file 
named SQUARO.REL and printing the listing on your terminal. A shorter notation of this 
same command line takes advantage of default file-name extensions assumed by the 
compiler: 

A>COBOL SQUARO,TTY:=SQUARO 
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The shortest notation of all uses a compilation switch to force generation of an object file 
that defaults to the filename SQUARO-REL: 

A>COBOL ,TTY:=SQUARO/R 

These three example commands all produce exactly the same results. A full description 
of the command line syntax is given in section 2. 

Once the source program is compiled, the final step before execution is to load the 
program with the Linking Loader L80. This step converts your relocatable object program 
into an absolute version and combines it with the COBOL-80 runtime system. This 
absolute version is built in memory, where it may then be saved on disk, executed 
directly, or both. The following is a command to load SQUARO and execute it without 
saving the absolute version. 

A>L80 SQUARO/G 

L80 assumes the extension .REL for the file SQUARO that is to be loaded. Once 
SQUARO has completed execution, you could not execute it again without performing the 
load command, since the absolute version was not saved. To save the absolute version in a 
disk file without executing it directly, type: 

A>L80 SQUARO/N,SQUARO/E 

Then to execute the program, simply type: 

A>SQUARO 

Since the absolute version is saved, it may be executed at any time without performing 
the load step. To combine the 2 examples so that the absolute version is saved and then 
executed directly, type: 

A>L80 SQUARO/N,SQUARO/G 

Refer to section 3 of this guide and to the Microsoft Utility Software Manual for a full 
description of L80 commands. 
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Section 2 
COMPILING COBOL PROGRAMS 



2.1 COBOL-80 Command Line Syntax 

The COBOL-80 compiler reads your COBOL source program file as input and produces a 
listing and relocatable object version of your program. The command line invokes the 
COBOL Compiler and tells it the names of the 3 files to use. The syntax of the line is to 
type COBOL followed by a space, followed by a command string, as described below. 
COBOL-80 is read from the disk and then examines the command string. If it is OK, 
compilation begins. If not, it types the message "?Command Error" followed by an 
asterisk prompt, then waits for another command string. When compilation is complete, 
COBOL-80 always exits to the operating system. 

The format of a COBOL-80 command string is: 

objectfile,listfile=:sourcefile 

The separator characters are the comma and the equal sign. No spaces are allowed. The 
terms used in the format are: 

objectfile 

the name of the file to which the object program is to be written 

listfile 

the name of the file to which the program listing is to be written 

sourcefile 

the name of the COBOL program source file 

Each file can be the name of a disk file or the name of a system device. The full 
description of a file name depends on your operating system. For CP/M, a file description 
has the form: 

device:filename.extension 
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Here the separators are the colon and period, and the terms mean: 

device 

the name of the system device, which can be a disk drive, terminal, line 
printer, or other device supported by the operating system. If the device is 
a disk, the filename must also be given. If not, the device name itself is 
the full file description. COBOL-80 recognizes the following symbolic 
device names: 

TTY: for the console terminal 
LST: for the system printer 
RDR: for the high-speed reader 

filename 

the name of the file on disk. If filename is specified without a device, the 
current disk is assumed as the device. 



•extension 

the extension of the filename given, 
defaults are assumed: 

.COB for the source program file 

.PRN for the listing file 

.REL for the object program file 



If not specified, the following 



In the command string, the objectfile, listfile, or both may be omitted. If neither a listing 
file nor an object file is requested, COBOL-80 will check for errors and print the total on 
the console. If nothing is typed to the left of the equals sign, an object file is written on 
the same device with the same filename as the source file, but with the default extension 
for object files. 



Examples: 
Command String 
,=PAYROLL 

=PAYROLL 
,TTY:=PAYROLL 

PAYOBJ,LST:=PAYROLL 

PAYOBJ=a:PAYROLL 

PAYROLL,PAYROLL=PAYROLL 



Effect 

Compiles the source from PAYROLL.COB and 
produces only an error count, which is displayed 
on the console. 

Compiles PAYROLL.COB and places the object 
into PAYROLL.REL. No listing is generated. 

Compiles the source from PAYROLL.COB and 
places the program listing on the terminal. No 
object program is generated. 

Compiles the source from PAYROLL.COB, places 
the listing on the printer, and places the object 
into PAYOBJ.REL. 

Compiles PAYROLL.COB from disk B and places 
the object into PAYOBJ.REL. No listing is 
generated. 

Compiles PAYROLL.COB, places the listing into 
PAYROLL.PRN, and places the object into 
PAYROLL.REL. 
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2*2 Compiler Switches 



The command string may be modified by appending one or more switches, which affect 
the compilation procedure as described below. To add a switch, type a slash followed by 
the one-character switch name. 

Switch Action 

R Force the compiler to generate an object file. This shorthand 

notation causes the compiler to write the object file on the same 
disk and with the same filename as the source file, but with the 
default extension for object files. 

L Force the compiler to generate a listing file. As with /R, this 

notation causes the compiler to write the listing file on the same 
disk and with the same filename as the source file, but with the 
default extension for listing files. 

P Each /P allocates an extra 100 bytes of stack space for the 

compiler's use. Use /P if stack overflow errors occur during 
compilation (see section 2.3 below). Otherwise /P is not needed. 

Examples of command strings using switches: 

Command String Is Equivalent To 

,=PAYROLL/R PAYROLL=PAYROLL or ^PAYROLL 

,=B:PAYROLL/L ,B:PAYROLL=B:PAYROLL 

,=B:PAYROLL/R/L B:PAYROLL,B:PAYROLL=B:PAYROLL 

=PAYROLL/L/P PAYROLL,PAYROLL=PAYROLL/P 

2.3 Output Listings and Error Messages 

The listing file output by COBOL-80 is a line-by-line account of the source file with page 
headings and error messages. The page heading line is printed 3 lines from the top of the 
page and is followed by 2 blank lines. Each source line listed is preceded by a consecutive 
4-digit decimal number. This is used by the error messages at the end to refer back to 
lines in error, and also by the runtime system to indicate what statement has caused a 
runtime error after it occurs. 

Two classes of diagnostic error messages may be produced during compilation. 
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Low level flags are displayed directly below source lines on the listing when simple syntax 
violations occur. Remedial action is assumed in each case, as documented below, and 
compilation continues. If a low-level error occurs, a high-level diagnostic will be 
generated at the end of the listing that refers to the line number attached to the 
low-level error, so the error count given at the end includes both classes of errors. 



Flag Reason for Flag 

"QLIT"? Faulty quoted literal 

1. Zero length 

2. Improper continuation 

3. Premature end-of-file 
(before ending delimiter) 

LENGTH? Quoted literal length over 120 
characters, or numeric literal 
over 18 digits, or 'word' 
(identifier or name) over 30 
characters. 

CHRCTR? Illegal character 

PUNCT? Improper punctuation 

(e.g. comma not fol- 
lowed by a space). 

BADWORD Current word is malformed 
such as ending in hyphen, 
or multiple decimal points 
in a numeric literal. 

SEQ // Improper sequence number 

(includes case of out-of- 
order sequence number). 

NAME? Name does not begin with 

a letter (A - Z). 

PIC = X An improper Picture. 

COL. 7? An improper character 

appears in source line 
character 'column' 7, 
where only * - / D are 
permissible. 

AREA A? Area A, columns 8-12, is 
not blank in a 
continuation line. 



Remedial Action by Compiler 



Ignore and continue. 
Assume acceptable. 
Assume program end. 



Excessive characters 
are ignored. 



Ignore and continue. 
Assume acceptable. 

Ignore and continue. 

Accept and continue. 
Accept and continue. 



PIC X is assumed. 

Assume a blank 
in column 7. 



Ignore contents of 
Area A (assume blank). 
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High level diagnostic messages consist of two or three parts: 

!• The associated source line number — four digits, followed by a colon (:). 

2. An English explanation of the error detected by the compiler. If this text 
begins with /W/, then it is only a warning; if not, it is an error sufficiently 
severe to inhibit linkage and execution of an object program, 

3. (Optional) The program element cited at the point of error is listed. Design of 
the high level diagnostic message text is such that no list of 'messages and error 
codes' is necessary; the messages are self-explanatory. 

Regardless of whether there is a list device, or what the list device may be physically, a 
message displaying the total number of errors or warnings is always displayed on the 
console at the end of compilation. This allows you to make a simple change to a COBOL 
program, recompile it without a listing and still know whether the compiler encountered 
any questionable statements in the program. 

Two error messages that occur infrequently and are also displayed on the console must be 
noted. One is "?Memory Full" which occurs when there is insufficient memory for all the 
symbols and other information the compiler obtains from your source program. It 
indicates that the program is too large and must be decreased in size or split into 
separately compiled modules. The symbol table of data-names and procedure-names is 
usually the largest user of space during compilation. All names require as many bytes as 
there are characters in the name, and there is an overhead requirement of about 10 bytes 
per data-name and 2 bytes per procedure-name. On the average, each line in the DATA 
DIVISION requires about 14 bytes of memory during compilation, and each line in the 
PROCEDURE DIVISION requires about 3 1/4 bytes. 

The other error message, "?CompiIer Error", occurs when the compiler becomes 
confused. It is usually caused by one of two problems: either the stack has overflowed, in 
which case using the /P switch will solve it; or the compiler or one of the overlay files on 
the disk has been damaged, in which case you should try your backup copy. If neither of 
these solutions works, you can sometimes determine the cause by compiling increasingly 
larger chunks of your program, starting with only a few lines, until the error recurs. 
These two error conditions cause immediate termination of compilation. 

2.4 Files Used by COBOL-80 

In addition to the source, listing and object files used by COBOL-80, the following files 
should be noted. 

First, there is a file called STEXT.INT which the compiler always places on the current 
disk. It is used to hold intermediate symbolic text between pass one and pass two of the 
compiler. It is created, written, then closed, read, and then deleted before the compiler 
exits. Consequently, you should never run into it unless the compilation is aborted. 
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Another file of concern is the file to be copied due to a COPY verb in the COBOL 
progrann. (See the discussion of COPY in the COBOL-80 Reference Manual) . Remember 
that copied files cannot have COPY statements within them and the rest of the line after 
a COPY statement is ignored. 

Finally COBOL programs that use segmentation cause the loader to create a file for each 
independent segment of the program. The filenames are formed as follows. The filename 
itself is the PROGRAM-ID defined in the IDENTIFICATION DIVISION. The extension is 
.Vnn where nn is a two-digit hexadecimal number that is the segment number minus 49. 
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The Microsoft Linking Loader LINK-80 is used to convert the compiled relocatable object 
version of your program into an absolute version that is executable. It automatically 
combines the required portions of the COBOL runtime system with your object program. 
The loader is also used to link one or more subprograms together with a main program. 
These subprograms may be specified individually or extracted from a library, and may be 
written in COBOL, FORTRAN-80 or MACRO-80 assembly language. 



3.1 LINK>80 Command Line Syntax 

The complete syntax for LINK-80 commands is given in Chapter 4 of the Microsoft Utility 
Software Manual. However, some functions described there are not useful when loading 
COBOL programs. This section summarizes use of the loader for COBOL programs. 

You may invoke LINK-80 in one of two ways: either type L80 followed by a carriage 
return and enter a command string when the asterisk prompt is typed, or type L80 
followed by a space, followed by the command string on the same line. 

The command string is a list of filenames separated by commas. Each filename specified 
is brought into memory by the loader and placed at the next available memory address. 
Switches are used in the command string to specify functions the loader is to perform. 
The command string may be broken up into many small strings and entered on different 
lines. The loader will prompt with an asterisk and wait for more command strings until 
one with a G or E switch has been processed and the loader exits to the operating system. 
Filenames are specified in the. same manner as for the compiler, except that the default 
extension is always .REL for files to be read by the loader. Such files are all expected to 
be in relocatable object format, so they must have been previously compiled (or 
assembled). 
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Switches most useful when loading COBOL programs are: 
Switch Effect 



filename/N 
/E 



/G 



Directs the loader to save the executable program on disk with 
name <filename> when the loading process is complete. 

Directs the loader to complete the loading process and exit to 
the operating system. The loader searches COBLIB.REL and 
CRTDRV.REL to resolve undefined global symbols* The final 
step is to save the executable program on disk, provided that the 
/N switch was specified. 

Directs the loader to complete the loading process and begin 
execution of the program. As with /E, the COBOL runtime 
library is searched, and the executable program is saved if /N 
was specified. 



Switches used occasionally when loading COBOL programs are: 

Switch Effect 

/R Immediately resets the loader to its initial state. The effect is 

as if the loader was aborted and then reloaded from disk. 

filename/S Directs the loader to search <filename> to resolve undefined 

global symbols. This command is used to selectively load 
CALLed subroutines from a user-built library. 

/M Prints a map of all global symbols and their values. Undefined 

globals appear with an asterisk after the name. 

/U Prints a list of all undefined global symbols. 



COBOL-80 User's Guide - Release 4 13 

LOADING COBOL PROGRAMS 



Examples: 

Command String 

MYPROG,SVPROG/N/E 

Loads MYPROG.REL, saves the absolute version in SVPROG.COM and exits to 
the operating system, 

MYPROG/G 

Loads MYPROG.REL and begins execution without saving the absolute version. 

MYPROG,SUBPRl,B:SUBPR2,MYPROG/N/E 

Loads MYPROG.REL,SUBPRLREL, and B:SUBPR2.REL. Saves the absolute 
version in MYPROG.COM and exits to the operating system. 

MYPROG/N,MYPROG,MYLIB/S/E 

Loads MYPROG.REL searches MYLIB.REL for subroutines referenced by 
"CALL*' statements, saves the absolute version in MYPR0G.COM and exits to 
the operating system. 



3.2 Subprograms 

If you have organized your program into a main module and one or more subprogram 
modules, the loader can combine them into one executable program. Before loading, 
compile (or assemble) all modules so that you have a relocatable object version of each. 
Then execute the loader and specify in the command string the name of each module you 
want to load. The modules may be specified in any order. For example, if you have a 
compiled main program file MAINPG.REL and 2 subprogram files SUBPRl.REL and 
SUBPR2.REL, you may load the executable program and save it with any of the following 
load commands: 

1. L80 MAINPG/N,MAINPG,SUBPR1,SUBPR2/E 

2. L80 
*MAINPG/N,MAINPG,SUBPR1,SUBPR2 
VE 

3. L80 SUBPR1,SUBPR2 
*MAINPG/N 
*MAINPG/E 
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3,3 Function Libraries 

The Microsoft Library Manager LIB-80 (CP/M versions only) allows you to collect any 
nunnber of subprograms into a single file (a library) that can be searched by the loader. 
For example, if you have six subprograms named SUBPRl.REL through SUBPR6.REL that 
are used by different main programs, you could make them into a library with the 
following command. 

LIB 
*USRLIB=SUBPR1,SUBPR2,SUBPR3,SUBPR4,SUBPR5,SUBPR6/E 

This will create a library file named USRLIB.REL. (See Section 3 of the Microsoft Utility 
Software Manual for a full description of LIB-80). Then if you have a main program 
MAINPG that CALLS SUBPR2 and SUBPR6, the load command: 

L80 MAINPG/N,MAINPG,USRLIB/S/E 

will load MAINPG and search USRLIB for SUBPR2 and SUBPR6. 

When making a library, you need to make sure that all subprogram ID's are unique. Since 
all COBOL runtime routines in COBLIB have names that begin with dollar sign, you should 
avoid the dollar sign in naming your subprograms. 
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Section 4 
EXECUTING COBOL PROGRAMS 



You may execute a COBOL program in any of three ways. The first is to use the G switch 
in the loader command string as described in section 3.1. The second is simply to type the 
name of an executable program file as saved by using the N switch in the loader command 
string. Finally, you may execute a program directly from within another COBOL program 
by using the CALL or CHAIN statement. Refer to Chapter 5 of the COBOL-80 Reference 
Manual for an explanation of program CALL and CHAIN. 



^"■^ 'I'he Runtime System 

The relocatable object version of your program produced by the compiler is not 8080 or 
Z80 machine code. Instead, it is in the form of a special object language designed 
specifically for COBOL instructions. The COBOL-SO runtime system executes your 
program by examining each object language instruction and performing the function 
required. This includes all processing needed to handle CRT, printer, and disk file input 
and output. 

The runtime system consists of a number of machine language subroutines collected into a 
library named COBLIB.REL and a CRT driver named CRTDRV.REL. When you load your 
COBOL program, COBLIB is automatically searched by the loader to find and load 
routines that are required to perform the instructions in your source program. The 
number of routines needed depends on the number of COBOL language features you have 
used in your main program and subprograms. If DISPLAY or ACCEPT statements are 
included in the source program, the loader automatically searches the file CRTDRV.REL 
to include the terminal-dependent functions. 

The amount of memory required by a COBOL program at runtime equals the amount 
required to store the data items defined in the DATA DIVISION, plus about 500 bytes per 
file, plus about 12 bytes per line of the PROCEDURE DIVISION, plus up to 24K bytes for 
the runtime system. 



4.2 Printer File Handling 

Printer files should be viewed simply as a stream of characters going to the printer. 
Records should be defined simply as the fields to appear on the printer. No extra 
characters are needed in the record for carriage control. Carriage return, line feed and 
form feed are sent to the printer as needed between lines. Note however, that blank 
characters (spaces) on the end of a print line are truncated to make printing faster. 
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No "VALUE OF" clause should be given for a PRINTER file in the FD, but "LABEL 
RECORD IS OMITTED" must be specified. The BLOCK clause must not be used for 
printer files. 



4.3 Disk File Handling 

Disk files must have "LABEL RECORD IS STANDARD" declared and have a "VALUE OF" 
clause that includes a File ID. File ID formats are described in the Utility Software 
Manual. Block clauses are checked for syntax but have no effect on any type file. 

The format of regular SEQUENTIAL organization files is that of a tv/o-byte count of the 
record length followed by the actual record, for as many records as exist in the file. The 
LINE SEQUENTIAL organization has the record followed by a carriage return/line feed 
delimiter, for as many records as exist in the file. Soth organizations pad any remaining 
space of the last physical block with control-Z characters, indicating end-of-file. To 
make maximum use of disk space, records are packed together with no unnecessary bytes 
in between. 

The format of RELATIVE files is always that of fixed length records of the size of the 
largest record defined for the file. No delimiter is needed, and therefore none is 
provided. Deleted records are filled with hex value '00'. Additionally, six bytes are 
reserved at the beginning of the file to contain system bookkeeping information. 

The format of INDEXED files is too complicated to include in this document. It is a 
complex mixture of keys, data, linear pointers, deletion pointers, and scramble-function 
pointers. It is doubtful that the COBOL programmer would require access to such 
information. 



4.4 CRT Handling 

4.4.1 Terminal Output 

All output to the terminal is done by the DISPLAY statement. Characters are sent one at 
at time by the DISPLAY runtime module or by the CRT driver. If no cursor positioning 
was specified for any of the displayed items, a carriage-return and line-feed are sent 
following the last displayed item. Otherwise, no assumptions about carriage control are 
made by the DISPLAY module. 
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^•4.2 Keyboard Input 

All input from the keyboard is done by the ACCEPT statement. One of two methods of 
input are used, depending on the type of ACCEPT being performed. 

For a format 2 ACCEPT, a full line of input is typed, using the operating system facilities 
for character echo and input editing, ending with a carriage return. For this type, the 
character codes defined in the CRT driver have no effect. 

For a format 3 or 4 ACCEPT, each character typed is read directly by the runtime 
ACCEPT module by using a call to the operating system. The ACCEPT module performs 
all necessary character echo and input editing functions. The editing control characters, 
function keys, and terminator keys are defined in the CRT driver (see Appendix A). 



4.5 Runtime Errors 

Some programming errors cannot be detected by the compiler but will cause the program 
to terminate prematurely when it is being executed. Each of those errors produces a 
four-line synopsis, printed on the console. 

** RUN-TIME ERR: 
reason (see list below) 
line number 
program-id 

The possible reasons for termination, with additional explanation, are listed below. 

REDUNDANT OPEN Attempt to open a file that is already open. 

DATA UNAVAILABLE Attempt to reference data in a record of a file that is not 

open or has reached the "AT END" condition. 

SUBSCRIPT FAULT A subscript has an illegal value (usually, less than 1). This 

applies to an index reference such as I + 2, the value of which 
must not be less than 1. 

INPUT/OUTPUT Unrecoverable I/O error, with no provision in the user's 

COBOL program for acting upon the situation by way of an AT 
END clause, INVALID KEY clause, FILE STATUS item, 
DECLARATIVE procedure, etc. 

NON-NUMERIC DATA Whenever the contents of a numeric item does not conform to 

the given PICTURE, this condition may arise. You should 
always check input data, if it is subject to error (because 
"input editing" has not yet been done) by use of the NUMERIC 
test. 
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PERFORM OVERLAP 

CALL PARAMETERS 
ILLEGAL READ 
ILLEGAL WRITE 

ILLEGAL REWRITE 

REWRITE; NO READ 

REDUNDANT CLOSE 
OBJ. CODE ERROR 

FEATURE UNIMPL. 

GO TO. (NOT SET) 

FILE LOCKED 
READ BEYOND EOF 
DELETE; NO READ 

ILLEGAL DELETE 
ILLEGAL START 
NO CRT DRIVER 

SEG nn LOAD ERR 



An illegal sequence of PERFORMS as, for example, when 
paragraph A is performed, and prior to exiting from it another 
PERFORM A is initiated. 

There is a disparity between the number of parameters in a 
calling program and the called subprogram. 

Attempt to READ a file that is not open in the input or I-O 
mode. 

Attempt to WRITE to a file that is not open in the output mode 
for sequential access files, or in the output or I-O mode for 
random or dynamic access files. 

Attempt to REWRITE a record in a file not open in the I-O 
mode. 

Attempt to REWRITE a record of a sequential access file when 
the last operation was not a successful READ. 

Attempt to close file that is not open. 

An undefined object program instruction has been 
encountered. This should occur only if the absolute version of 
the program has been damaged in memory or on the disk file. 

An object program instruction that calls for an unimplemented 
feature has been encountered. This should occur only because 
of a damaged object program. 

Attempt to execute an uninitialized alterable paragraph 
containing only a null GO statement. 

Attempt to OPEN after earlier CLOSE WITH LOCK, 

Attempt to read (next) after already encountering end-of-file. 

Attempt to DELETE a record of a sequential access file when 
the last operation was not a successful READ. 

Relative file not opened for I-O. 

File not opened for input or I-O. 

An ACCEPT or DISPLAY statement using cursor positioning is 
being executed, but no CRT driver has been selected. (See 
Appendix A of this guide.) 

An unrecoverable read error has occurred while trying to load 
a segment of a segmented program. The two digits nn are the 
hexadecimal notation of the segment number minus 49 and 
match the name of the file extension (.Vnn) on the disk. 
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In the case of program CHAINing, error messages may be generated by the CHAIN 
processing module* These errors are of the form "*'*CHAIN: problem" and also cause 
termination of the program. See Appendix B for the list of CHAIN error messages. 
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Appendix A 
CONFIGURING THE CRT 



A.l General Instructions 

To enable the interactive ACCEPT and DISPLAY functions, COBOL-80 requires a 
ternninal driver module that provides primitive terminal-dependent functions. The system 
expects to find this module under the name CRTDRV.REL when programs are linked with 
LSO. 

A module named CRTDRV is provided with each Release 4 COBOL disk. This is a default 
dummy driver that will enable programs to link successfully and will provide support for 
the ANSI standard ACCEPT and DISPLAY statements. Programs that use cursor 
positioning in ACCEPT or DISPLAY statements and link with the default driver will not 
run successfully; they will abort with the "NO CRT DRIVER" runtime error message. 

The CRTDRV module should be replaced with the driver appropriate to the type of 
terminal being used before linking any COBOL programs compiled with Release 4. To do 
this, simply copy the appropriate driver to CRTDRV.REL. Microsoft has provided drivers 
for a wide range of popular terminals; these are listed below. If none of these drivers is 
suitable, one may be constructed; see section A. 3: "Writing a CRT Driver". 

The CRT driver modules supplied by Microsoft are relocatable object files whose names 
begin with the letters CD (for CRT Driver). The MACRO-80 source code for each driver 
is also included. Any driver will support more than one type of terminal if the terminals 
have compatible control sequences. If your terminal is not listed below, check section A. 2 
to compare your terminal's function codes with those of the supplied terminal drivers. If 
your terminal matches the code for any supplied driver, use it. The terminals and 
associated drivers are: 

1. ANSI standard terminal CDANSI 

2. Lear-Siegler ADM3-A CDADM3 

3. Beehive 100, 150 CDBEE 

4. Microbee 2 CDBEE 

5. Cromemco 3101, 3102 CDBEE 

6. SOROC IQ CDSROC 

7. Hazeltine 1500 CDHZ15 

8. Heath WH19 CDWH19 

9. DEC VT52 CDWH19 

10. ADDS Regent Terminals * CDADDS 

11. Perkin-Elmer CDPERK 

12. Zentec Zephr CDZEPH 

13. Intertec Superbrain CDISB 

14. IMSAI VIO CDADM3 

* Supports ADDS Regent 40, 60, 100, and 200 terminals. The highlight video 
codes are not available on the Regent 20 and 25, but the CDADDS driver can 
be used if that code is removed. 
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A.2 Terminal Charts 

The following pages describe the characteristics of the terminals for which 
drivers are supplied on your distribution disk. There is one page for each 
terminal supported. 

Section I of each page defines the keys that are recognized by COBGL-80 to 
perform the functions of ACCEPT. The value listed under the heading "Escape 
Code" is the integer that is available using a format 1 ACCEPT. ..FROM 
ESCAPE KEY if the key caused termination of a format 3 or format 4 
ACCEPT statement. The value listed under the heading "Input Code" is the 
hexadecimal code generated by the terminal when that key is typed. The 
entry under "Key Label" gives the name of the key as shown on the keyboard. 

Section II of each page shows the sequences of codes that are sent to the 
terminal from COBOL-80 to perform the functions of DISPLAY and ACCEPT. 
Spaces are shown to separate codes in the list, but they are not part of the 
sequence sent to the terminal. Each two-digit number represents an absolute 
hexadecimal value. All other codes describe standard ASCII character codes, 
except for some shorthand abbreviations, which have the following 
explanations: 



Rl The binary row (line) number plus decimal 31. 

R2 The row number converted to 2 ASCII digits, sent high digit first. 

CI The binary column number plus decimal 31. 

C2 The column number converted to 2 ASCII digits, sent high digit first. 
C3 If the column number is less than 32, a decimal 95 is added to the 
number. Otherwise, column number minus one is used. 

N/A Function not available on this terminal. 

El If the cursor is at the home position, a clear screen code (hexadecimal 
lA) is used. Otherwise, enough spaces are sent to blank the remainder of 
the screen and the cursor is moved back to its original position. 

E2 Enough spaces are sent to blank the remainder of the line and the cursor 
is moved back to its original position. 

Nl Ten null (binary zero) characters. 
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CDADDS 



ADDS Regent Terminals 
24 Lines 80 Columns 



I. Keyboard Input 






Inpu 


t Code 


Key Label 


A. Editing Keys 












1. Line delete/Field delete 






15 


CONTROL-U 


2. Character delete 








7F 


DEL 


3. Forward Space 








06 


CONTROL-F 


4. Back Space 








08 


CONTROL-H 


5. Plus Sign 








2B 


+ 


6. Minus Sign 








2D 


- 


B. Terminator Keys 


Escape Code 


( Input Code 


Key Label 


1. Backtab 




99 




02 


CONTROL-B 


2. Escape 




01 




IB 


ESC 


3. Field terminators 




00 








a. Tab 








09 


CONTROL-I 


b. Carriage Return 








OD 


NEW LINE 


c. Line Feed 








OA 


LINE FEED 


C. Function Keys 


Escape Code 


Input Code 


Key Label 


1. 


02 






01 


CONTROL-A 


2. 


03 






03 


CONTROL-C 


3. 


04 






18 


CONTROL-X 


II. Outjjut Functions 






Code Sequence 




A. Set Cursor Position 






ESC Y Rl CI 




B. Backspace Cursor 






08 






C. Cursor On 






N/A 






D. Cursor Off 






N/A 






E. Erase to End of Screen 






ESCk 




F. Erase to End of Line 






ESC K 




G. Sound Bell 






07 






H. Set Highlight Mode 






ESC OP 




I. Reset Highlight Mode 






ESC (i 
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CDADM3 



Lear-Siegler ADM-3A 
24 Lines 80 Columns 



I. Keyboard Input 






Input Code 


Key Label 


A. Editing Keys 












1. Line delete/Field delete 






15 


CONTROL-L 


2. Character delete 








7F 


DEL 


3. Forward Space 








OC 


CONTROL-L 


4. Back Space 








OB 


CONTROL-h 


5. Plus Sign 








2B 


+ 


6. Minus Sign 








2D 


- 


B. Terminator Keys 


Escape 


Code 


Input Code 


Key Label 


1. Backtab 




99 




02 


CONTROL-E 


2. Escape 




01 




IB 


ESC 


3. Field terminators 




00 








a. Tab 








09 


CONTROL -I 


b. Carriage Return 








OD 


RETURN 


c. Line Feed 








OA 


LINE FEED 


C. Function Keys 


Escape Code 


Input Code 


Key Label 


1. 


02 






01 


CONTROL-A 


2. 


03 






03 


CONTROL-C 


3. 


04 






18 


CONTROL-X 


II. Output Functions 






Code Sequence 




A. Set Cursor Position 






ESC 


= R1C1 




B. Backspace Cursor 






08 






C. Cursor On 






N/A 






D. Cursor Off 






N/A 






E. Erase to End of Screen 






El 






F. Erase to End of Line 






E2 






G. Sound Bell 






07 






H. Set Highlight Mode 






N/A 






I. Reset Highlight Mode 






N/A 
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CDANSI 



ANSI Standard Terminal 
24 lines 80 Columns 



I. Keyboard Input 






Input Code 




Key Label 


A. Editing Keys 












1. Line delete/Field delete 




15 




CONTROL-U 


2. Character delete 






7F 




DEL, RUB 


3. Forward Space 






06 




CONTROL -F 


4. Back Space 






OB 




CONTROL-H 


5. Plus Sign 






2B 




+ 


6. Minus Sign 






2D 




• 


B. Terminator Keys 


Escape 


Code Input Code 


Key Label 


1. Backtab 




99 




02 


CONTROL-B 


2. Escape 




01 




IB 


ESC 


3. Field terminators 




00 








a. Tab 








09 


TAB, CONTROL-I 


b. Carriage Return 








OD 


RETURN, ENTER 


c. Line Feed 








OA 


LINE FEED 


C. Function Keys 


Escape Code Input Code 


Key Label 


1. 


02 




01 




CONTROL-A 


2. 


03 




03 




CONTROL-C 


3. 


04 




18 




CONTROL-X 


II. Output Functions 






Code Sequence 




A. Set Cursor Position 






ESC [ R2 ; C2 f 




B. Backspace Cursor 






08 






C. Cursor On 






ESC [ > 5 1 






D. Cursor Off 






ESC [ > 5 h 






E. Erase to End of Screen 






ESC [ J 






F. Erase to End of Line 






ESC [ K 






G, Sound Bell 






07 






H. Set Highlight Mode 






ESC [ 7 m 






I. Reset Highlight Mode 






ESC [ m 
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CDBEE 



Beehive Terminals 
24 lines 80 Colunnns 



I. Keyboard Input 








Input Code 


Key Label 


A. Editing Keys 












1. Line delete/Field delete 






15 


CGNTRGL-U 


2. Character delete 








7F 


DEL 


3. Forward Space 








06 


CONTROL -F 


4. Back Space 








08 


CONTROL-H 


5. Plus Sign 








2B 


+ 


6. Minus Sign 








2D 


- 


B. Terminator Keys 




Escape 


Code Input Code 


Key Label 


1. Backtab 






99 


02 


CONTROL-8 


2. Escape 






01 


IB 


ESC 


3. Field terminators 






00 






a. Tab 








09 


TAB, CONTROL-I 


b. Carriage Return 








OD 


RETURN 


c. Line Feed 








OA 


LINE FEED 


C. Function Keys 


Escape 


Code Input Code 


Key Label 


1. 




02 




01 


CONTROL-A 


2. 




03 




03 


CONTROL-C 


3. 




04 




18 


CONTROL-X 


11. Output Functions 








Code Sequence 




A. Set Cursor Position 








ESC F Rl CI 




B. Backspace Cursor 








08 




C. Cursor On 








N/A 




D. Cursor Off 








N/A 




E. Erase to End of Screen 








ESC J Nl 




F. Erase to End of Line 








ESCK 




G. Sound Bell 








07 




H. Set Highlight Mode 








ESC 1 




I. Reset Highlight Mode 








ESC m 
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CDHZ15 



Hazeltine 1500 Series Terminals 
24 Lines 80 Columns 



I. Keyboard Input 








Input Code 


Key Label 


A. Editing Keys 














1. Line delete/field delete 








15 


CONTROL-U 


2. Character delete 










7F 


DEL 


3. Forward Space 










5D 


] 


4. Back Space 










08 


BACK SPACE 


5, Plus Sign 










2B 


+ 


6. Minus Sign 










2D 


- 


B. Terminator Keys 




Escape 


Code 


Input Code 


Key Label 


1. Backtab 






99 




5C 


■ \ 


2. Escape 






01 




IB 


ESC 


3. Field terminators 






00 








a. Tab 










09 


TAB 


b. Carriage Return 










OD 


RETURN 


c. Line Feed 










OA 


LINE FEED 


C. Function Keys 


Escape Code 


Input Code 


Key Label 


1. 




02 






01 


CONTROL-A 


2. 




03 






03 


CONTROL-C 


3. 




04 






18 


CONTROL-X 


II. Output Functions 








Code Sequence 




A. Set Cursor Position 








~ DCl C3 Rl 




B. Backspace Cursor 








08 






C. Cursor On 








N/A 






D. Cursor Off 








N/A 






E. Erase to End of Screen 








"• CAN 




F. Erase to End of Line 








~SI 






G. Sound Bell 








07 






H. Set Highlight Mode 








~US 






I. Reset Highlight Mode 








~EM 
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GDI SB 



Intertec Superbrain 
24 Lines 80 Columns 



I. Keyboard Input 








Input Code 


Key Label 


A. Editing Keys 














1. Line delete/Field delete 








18 


CONTROL-X 


2. Character delete 










7F 


DEL 


3. Forward Space 










06 


CONTROL-F 


4. Back Space 










08 


BACK SPACE 


5. Plus Sign 










2B 


+ 


6. Minus Sign 










2D 


" 


B. Terminator Keys 




Escape 


Code 


Input Code 


Key Label 


1. Backtab 






99 




02 


CONTROL-B 


2. Escape 






01 




IB 


ESC 


3. Field terminators 






00 








a. Tab 










09 


TAB 


b. Carriage Return 










OD 


RETURN 


c- Line Feed 










OA 


LINE FhLD 


C. Function Keys 


Escape 


Code 


Input Code 


Key Label 


1. 




02 






01 


CONTROL-A 


2. 




03 






03 


CONTROL-C 


3. 




04 






04 


CONTROL-D 


II. Output Functions 








Code Sequence 




A. Set Cursor Position 








ESC Y Rl CI 




B. Backspace Cursor 








08 






C. Cursor On 








N/A 




' 


D. Cursor Off 








N/A 






E. Erase to End of Screen 








ESC 


~k 




F. Erase to End of Line 








ESC 


"K 




G. Sound Bell 








07 






H. Set Higinlight Mode 








N/A 






I. Reset Highlight Mode 








N/A 
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CDPERK 



Perkin - Elmer Terminals 
24 Lines 80 Columns 



I. Keyboard Input 




Input Code 




Key Label 


A. Editing Keys 










1. Line delete/Field delete 


15 




CONTROL-U 


2. Character delete 




7F 




DEL 


3. Forward Space 




06 




CONTROL-F 


4. Back Space 




08 




BACK SPACE 


5. Plus Sign 




2B 




+ 


6. Minus Sign 




2D 




- 


B. Ternriinator Keys 


Escape 


Code Input Code 


Key Label 


1. Backtab 


99 




02 


CONTROL-B 


2. Escape 


01 




IB 


ESC 


3. Field terminators 


00 








a. Tab 






09 


TAB 


b. Carriage Return 






OD 


RETURN 


c. Line Feed 






OA 


LINE FEED 


C. Function Keys 


Escape Code Input Code 


Key Label 


1. 


02 


01 




CONTROL-A 


2. 


03 


03 




CONTROL-C 


3. 


04 


18 




CONTROL-X 


II. Output Functions 




Code Sequence 




A. Set Cursor Position 




ESC X Rl ESC Y CI 




B. Backspace Cursor 




08 






C. Cursor On 




N/A 






D. Cursor Off 




N/A 






E. Erase to end of screen 




ESC J 






F. Erase to end of line 




ESC I 






G. Sound Bell 




07 






H. Set Highlight nnode 




N/A 






I. Reset Highlight Mode 




N/A 
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CDSROC 



SOROC IQ Terminals 
24 Lines 80 Colunnns 



I. Keyboard Input 






Input Code 


Key Label 


A. Editing Keys 










1. Line delete/Field del 


ete 




15 


CONTROL-U 


2. Character delete 






7F 


DEL 


3. Forward Space 






OC 


CONTROL-L 


4. Back Space 






08 


CONTROL-H 


5. Pius Sign 






2B 


+ 


6. Minus Sign 






2D 


- 


B. Terminator Keys 


Escape 


Code Input Code 


Key Label 


1. Backtab 




99 


02 


CONTROL-B 


2. Escape 




01 


IB 


ESC 


3. Field terminators 




00 






a. Tab 






09 


CONTROL-I 


b. Carriage Return 






OD 


RETURN 


c. Line Feed 






OA 


LINE FEED 


C. Function Keys 


Escape 


Code Input Code 


Key Label 


1. 


02 




01 


CONTROL-A 


2. 


03 




03 


CONTROL-C 


3. 


04 




18 


CONTROL-X 


II. Output Functions 






Code Sequence 




A. Set Cursor Position 






ESC = Rl CI 




B. Backspace Cursor 






08 




C. Cursor On 






N/A 




D. Cursor Off 






N/A 




E. Erase to End of Screen 






ESC Y 




F. Erase to End of Line 






ESCT 




G. Sound Bell 






07 




H. Set Highlight Mode 






N/A 




I. Reset Highlight Mode 






N/A 
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CDWH19 






Heath WH19/DEC VT52 
24 Lines 80 Columns 




I. Keyboard Input 








Input Code 


Key Label 


A. Editing Keys 












1. Line delete/Field delete 






15 


CONTROL-U 


2. Character delete 








7F 


DELL 1 E 


3. Forward Space 








06 


CONTROL-F 


4. Back Space 








08 


BACK SPACE 


5. Plus Sign 








2B 


+ 


6. Minus Sign 








2D 


— 


B. Terminator Keys 




Escape 


Code Input Code 


Key Label 


1. Backtab 






99 


02 


CONTROL-B 


2. Escape 






01 


IB 


ESC 


3. Field terminators 






00 






a. Tab 








09 


TAB, CONTROL-I 


b. Carriage Return 








OD 


RETURN 


c. Line Feed 








OA 


LINE FEED 


C. Function Keys 


Escape 


Code Input Code 


Key Label 


1. 




02 




01 


CONTROL-A 


2. 




03 




03 


CONTROL-C 


3. 




04 




18 


CONTROL-X 


II. Output Functions 








Code Sequence 




A. Set Cursor Position 








ESC Y Rl CI 




B. Backspace Cursor 








08 




C. Cursor On 








ESCy 5 




D. Cursor Off 








ESC X 5 




E. Erase to End of Screen 








ESC J 




F. Erase to End of Line 








ESCK 




G. Sound Bell 








07 




H. Set Highlight Mode 








ESCp 




I. Reset Highlight Mode 








ESCq 
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CDZEPH 



Zentec Zephr 

24 Lines 80 Columns 



I. Keyboard Input 






Input Code 


Key Label 


A. Editing Keys 










1. Line delete/Field delete 






15 


CONTROL-U 


2. Character delete 






7F 


DEL 


3. Forward Space 






06 


CONTROL-F 


4. Back Space 






08 


CONTRGL-H 


5. Plus Sign 






2B 


+ 


6. Minus Sign 






2D 


- 


B. Terminator Keys 


Escape Code Input Code 


Key Label 


1. Backtab 




99 


02 


CONTROL-B 


2. Escape 




01 


IB 


ESC 


3. Field terminators 




00 






a. Tab 






09 


TAB, CGNTROL-I 


b. Carriage Return 






OD 


RETURN 


c. Line Feed 






OA 


LINE FEED 


C. Function Keys Es( 


;ape 


Code Input Code 


Key Label 


1. 


02 




01 


CONTROL-A 


2. 


03 




03 


CONTRGL-C 


3. 


04 




18 


CGNTRGL-X 


II. Output Functions 






Code Sequence 




A. Set Cursor Position 






ESC Rl CI 




B. Backspace Cursor 






08 




C. Cursor On 






N/A 




D. Cursor Off 






N/A 




E. Erase to End of Screen 






ESC Y Nl 




F. Erase to End of Line 






ESCT 




G. Sound Bell 






07 




H. Set Highlight Mode 






ESCG4 




I. Reset Highlight Mode 






ESC GO 
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A.3 Writing a CRT Driver 

A CRT driver should be written in assembly language and assembled with the Microsoft 
assembler M80. It consists of 14 entry points that must be declared as global labels by 
using M80 ENTRY statements. The source code of all drivers is supplied on your 

distribution disk (files named CD .MAC) to serve as examples and reference for the 

following explanation. 

Once the CRT driver is written, you can test all the functions and key codes by using the 
program CRTEST that is supplied on your distribution disk. Compile it, link it with your 
CRT driver using L80, and execute it, following the instructions it provides. 

Five of the entry points simply contain data that describe the terminal and keyboard. 
$CRLEN is a byte that contains the number of lines on the terminal and $CRWID contains 
the number of columns. $CLIST, $TLIST and $FLIST are sequences of bytes that define 
keyboard codes that invoke the functions of ACCEPT. Note that these codes are not sent 
to the terminal to perform the function; they merely declare the keys that should be 
recognized by the ACCEPT module. All of these codes should be unique. 

SCLIST defines the editing keys, which must be specified in the following sequence: 

1. Line delete (Field delete) 

2. Character delete 

3. Forward space (Cursor forward) 

4. Backspace (Cursor back) 

5. Plus sign 

6. Minus sign 

The list is terminated by a byte containing zero. 

$FLIST defines function keys that terminate a format 3 or a format 4 ACCEPT 
statement. The order of placement of codes in $FLIST determines the ESCAPE KEY 
value available to the ACCEPT ... FROM ESCAPE KEY statement. The first key 
generates a value of 02, the second 03, and so on, up to a maximum value of 39, The list 
is terminated by a byte containing zero. 

$TLIST defines several keys, all of which terminate format 3 type ACCEPT statements. 
First in the list must be the backtab key. If used in a format 4 ACCEPT, this key causes 
termination of the current field and the cursor to move to the previous input field, if one 
exists. If used in a format 3 ACCEPT, the backtab key terminates the ACCEPT and sets 
an escape code value of 99. Next in the list is the escape key. This key terminates either 
a format 3 or format 4 ACCEPT and sets an escape code value of 01. In addition, it 
causes the program to execute the ON ESCAPE clause of a format 4 ACCEPT. Finally, 
there is a list of normal field terminator keys, terminated by a zero byte. Any key in this 
list terminates the current input field and sets the escape code value to 00. Termination 
of the field ends a format 3 ACCEPT, and moves the cursor to the next field in a format 4 
ACCEPT. If the cursor was in the last input field, the entire ACCEPT statement is 
terminated- 
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The remaining 9 entry points are subroutines that perform terminal functions by sending 
codes to the terminal. Each code is sent by calling the external routine SCUTCH with the 
value in the A register. $OUTCH preserves the values in registers HL and DE. 

$SETCR moves the cursor to a specific position on the screen. Upon entry, register H 
contains the specified row (line) number and register L contains the column number. Note 
that COBOL considers the top line of the screen to be row 1 and the leftmost column to be 
column 1. 

SCURBK moves the cursor to the left one position without disturbing the displayed 
character at that position. Upon entry, register HL contains the current cursor position in 
sequential format (i.e., a number between 1 and n where n is screen width times length). 
Most terminals honor the ASCII backspace code to perform this function. 

$ALARM sounds the terminal's audible tone or bell. Most terminals honor the ASCII bell 
code to perform this function. 

SCUROF and $CURON instruct the terminal to inhibit or enable display of the cursor. 
Many terminals do not provide this facility, however, and a simple RET instruction is 
appropriate for drivers of those terminals. 

$ERASE clears that portion of the screen from the current cursor position to the end. 
The cursor must be left in its original position. Upon entry, register HL contains the 
current cursor position in sequential format. Some terminals, such as the ADM-3A, do not 
provide an escape sequence to perform this function. The example driver CDADM3 
provides a routine that sends enough blanks to clear the screen and then returns the cursor 
to its original position. This routine may be used for any terminal that does not provide 
its own erase function. 

$EOL clears that portion of the screen from the current cursor position to the end of the 
line, without moving the cursor. Upon entry, register H contains the current row number 
and L contains the current column. 

$HILIT puts the terminal in reverse video mode (or some other highlight mode if reverse 
video is not available). 

SLOLIT puts the terminal back in normal mode (cancels the effect of $HILIT). 
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This appendix describes the fornnat of parameters passed between a main program and a 
subprogram via a CALL USING statement or between two main programs via a CHAIN 
USING statement. This parameter linkage is handled entirely by the COBOL-SO runtime 
system if both programs are written in COBOL. However, if the CALLed or CHAINed 
program is written in assembly language or FORTRAN, sections B,l and 8,2 are of 
interest. 



B.l Subprogram Calling Mechanism 

It is possible for a COBOL program to call COBOL subprograms or to call FORTRAN or 
assembler subroutines. However, it is not possible, currently, for a FORTRAN or 
assembler program to call a COBOL subroutine. Therefore, this section pertains to 
COBOL programs which call FORTRAN or assembler subroutines. The calling sequence 
described below is identical to that of Microsoft's FORTRAN-SO as it calls FORTRAN or 
assembler subroutines. 

The COBOL runtime system transfers execution to a subroutine by means of a machine 
language CALL instruction. The subroutine should return via the normal assembler or 
FORTRAN return instruction. 

Parameters are passed by reference, that is, by passing the address of the parameter. The 
method of passing these addresses depends on the number of parameters. If the number of 
parameters is less than or equal to 3, they are passed in the registers: 

parameter 1 in HL 
parameter 2 in DE 
parameter 3 in BC 

If the number of parameters is greater than 3, then 1 and 2 are still passed in HL and DE, 
but BC points to a contiguous data block in memory which holds the list of parameter 
addresses. 

The subroutine can expect only as many parameters as are passed, and the calling program 
is responsible for passing the correct number of parameters. Neither the compiler nor the 
runtime system checks for the correct number of parameters. It is also entirely up to you 
to determine that the type and length of arguments passed the calling program are 
acceptable to the called subroutine. Note that alphanumeric data is the only type that is 
stored in the same format in COBOL and FORTRAN. None of the numeric types of data 
are interchangeable. 
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The stack space used by a COBOL program is contained within the program boundaries, so 
assembler programs that use the stack must not overflow or underflow the stack. The 
most certain way to assure safety is to save the COBOL stack pointer upon entering the 
routine and to set the stack pointer to another stack area. The assembler routine must 
then restore the saved COBOL stack pointer before returning to the main program. 

To call a subprogram, use the name of the subprogram in the COBOL CALL statement. If 
the subprogram is an assembler or FORTRAN program, the name is defined by an ENTRY, 
SUBROUTINE, or FUNCTION statement. The name of a COBOL subprogram is as given 
in the PROGRAM-ID paragraph. Then link the subprogram to the main program using 
LINK-80, as described in section 3.2 of this guide. 



B.2 CHAIN Parameters 

The parameters passed between programs with a CHAIN USING statement are stored at 
the highest available memory address. The memory layout is as follows, starting at the 
highest available address and proceeding towards location zero. First, 32 bytes are 
reserved for stack space. Then the first parameter in the USING list follows, preceded by 
its length in bytes. The parameter length is stored in two bytes, high-order byte first. 
The parameter itself is stored as a string of bytes in the same order as they were stored in 
the DATA DIVISION, beginning at the address of the length minus the length itself. Each 
parameter in the USING list follows in order, each preceded by its length. The CHAINed 
program must expect the same number and format of parameters as were passed, as no 
checking can be done by the compiler or runtime system. 



1 <— highest memory location 



stack 
space 
32 bytes 



<— length of parameter 1 (high byte) 
<— length of parameter 1 (low byte) 
<— last byte of parameter 1 



<— first byte of parameter 1 
<— length of parameter 2 (high byte) 
<— length of parameter 2 (low byte) 
<— last byte of parameter 2 



Figure B-1 
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^•^ CHAIN Error Messages 

During CHAIN processing, the normal mechanisnn for reporting runtime errors may have 
been overlay ed by the new program. Therefore, the CHAIN processor generates its own 
error messages, which are of the form *'*^CHAIN: problem". The following is a list of 
possible "problems" and their causes. 



Bad file name 
File not found 
Out of Memory 



The syntax of the file name that is to be loaded is not valid. 

The specified file was not found on the disk. 

There was not sufficient memory available to load the new 
program. There must be enough memory for the larger of the 
CHAINing and CHAINed program, plus all CHAIN 
parameters, plus 256 bytes for the program loader. 
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This appendix is intended for those of you who are handy with a debugger and/or assennbly 
language and would like to change some of the built-in parameters of COBOL-80, 



C.l Source Program Tab Stops 

If tab characters (hex 09) are used in the COBOL source program, the compiler converts 
them into enough spaces to reach the next tab stop as defined in its internal TAB table. 
As delivered, the table defines 9 stops at the following columns (counting from column 1): 

7, 17, 25, 33, 41, 49, 57, 65, and 73 

These may be changed by patching the table, whose address is 7 bytes from the start of 
COBOL.COM. There is one byte in the table for each tab stop. You may supply any 
values you like, provided the numbers are in order and that there are still exactly 9 stops 
defined. 



C.2 Compiler Listing Page Length 

There is one byte in the compiler that defines the listing page length to be 55 (hex 37) 
lines. Its location is 6 bytes from the start of COBOL.COM and may be patched to any 
value between 1 and 255. 



C.3 Runtime Day, Date, Time, Line Number 

For all operating systems that do not provide date or time system calls, COBOL-80 uses 
the compiler release date for format 1 ACCEPT statements. For single-user systems, 
COBOL always uses *00' for the line number. If you have a multi-user system or access to 
a system clock (or would like to use some other fixed date and time), you may replace the 
runtime module that performs this function. To do this, write an assembly language 
module according to the instructions given below, assemble it with MACRO-80, and place 
it into COBLIB.REL using the library manager. Assuming you name the module 
ACPDAT.MAC, a LIB-80 command to place it in the library is: 
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LIB 

*NEWLIB=COBLIB<-.ACPDAT-l>, ACPDAT 

*C0BLIB<ACPDAT+1..>/E 

This will create NEWLIB.REL. You can then save COBLIB.REL and rename NEWLIB.REL 
to COBLIB.REL. 



ACPDAT Module 

Entry point: $ACPDT 

Externals: $EVAL,$GETOP,$FLAGS,$ESKEY,$MOVE 

This module handles the runtime support for the COBOL format 1 ACCEPT source 
statement: 

DAY 
DATE 
ACCEPT identifier FROM TIME 

ESCAPE KEY 
LINE NUMBER 

It may be changed by modifying the ACLINE routine and by adding ACTIME, ACDAY, and 
ACDATE to the skeleton module given below. Each of these routines is entered with the 
address of the target storage area in the HL register. Each must exit by executing a JMP 
$GETOP, as indicated in the skeleton. The individual routines have the following 
requirements: 

1. ACTIME - move an ASCII string representing the time (in form HHMMSSFF) to 

the target area. 

2. ACDAY - move an ASCII string representing the Julian date (in form YYJJJ) to 

the target area. 

3. ACDATE- move an ASCII string representing the date (in form YYMMDD) to 

the target area. 

4. ACLINE - move 2 ASCII digits representing the line (CRT) number to the target 

area. 

An external move routine is available to move a string of data from one address to 
another. It is used as follows: 

EXT $MOVE 

HL = address of source string 

DE = address of target area 

BC = length of the string in bytes 
CALL $MOVE 

HL = address of 1st byte beyond source 

DE = address of 1st byte beyond target 

BC = 
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Skeleton ACPDAT module: 



TITLE ACPDAT - ACCEPT DAY/DATE/TIME/ESC KEY/LINE NUM 

ENTRY $ACPDT 

EXT $EVAL,$GETOP,$FLAGS,$ESKEY 



$ACPDT: 


PGP 


H 






INX 


H 






MOV 


A,M 






INX 


H 






ANI 


7 






STA 


$FLAGS 


;SAVE ACCEPT OPTION 




CALL 


$EVAL 


;GET TARGET ADDRESS 




LDA 


$FLAGS 






CPI 


2 


jWHICH OPTION? 




JM 


ACDATE 


;DATE 




JZ 


ACDAY 


;DAY 




CPI 


4 






JC 


ACTIME 


jTIME 




JZ 


ACLINE 


;LINE NUMBER 


ACESC: 


XCHG 




jESCAPE KEY CODE FROM ACCEPT 




LHLD 


$ESKEY 






XCHG 






ACESCl: 


MOV 


M,D 






INX 


H 






MOV 


M,E 






JMP 


$GETOP 




ACLINE: 






;LINE (CRT) NUMBER - ALWAYS '00' 




LXI 


D,3030H 






JMP 


ACESCl 




ACTIME: 






:TIME: HHMMSSFF 



JMP 



ACDAY: 



$GETOP 



;DAY: YYJJJ 



JMP $GETOP 



ACDATE: 



;DATE: YYMMDD 



JMP $GETOP 

END 
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Many of the examples and instructions given in the rest of this document refer to 
procedures and file names specific to the CP/M operating system* The syntax of 
command strings is the same for all operating sytems; however, the file specifications and 
switch separator character may differ- The A> shown in some examples is a prompt that 
is typed by CP/M and is not part of the command- If you have a different operating 
system, the following sections give descriptions of differences you should note. 



D-1 TRSDOS Model H 

D.1.1 Filename Descriptions 

File specifications for COBOL-aO and LINK-aO have the same form as described in the 
TRS-80 Owners Manual, namely: 

filename/ext.passwordrdCdiskette name) 

The separator characters are the slash, period, and colon. 

D.1.2 Your Distribution Disk 

The names of the files on your distribution disk differ from the CP/M names and follow 
the TRSDOS file naming conventions. The disk contains the same files as a CP/M disk 
with the following exceptions: 

*Only the CRT driver for the Model 11 terminal is included 

*Some utility programs that are not available on the Model II are not included. They 
are: 

LiB-ao 

SEQCVT 
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D.1.3 Command Line Syntax 

The command string for COBOL-BO and LINK-80 have the same form under TRSDOS as 
under CP/M, However, the separator character for switches is a hyphen instead of a slash 
(since slash is used in TRSDOS file names) and the symbolic names of the console and 
printer devices are :TT and :LP respectively. Using the TRSDOS syntax, the following 
example shows how to compile, load, and execute the test program SQUARO/COB« 

TRSDOS READY 
COBOL ,:TT=SQUARO-R 
LBO SQUARO-N,SQUARO-E 
SQUARO 

The default file extensions assumed by COBOL-80 are 



/COB for the source program file 

/LST for the listing file 

/REL for the object program file 



D.1.4 DATE and TIME 



COBOL-80 uses the date and time supplied by TRSDOS to time-stamp the compiler listing 
page headings and to return the values requested by the ACCEPT TIME and DATE 
statements. 

D.L5 CRT Handling 

Since the Model II has a built-in keyboard and display monitor, COBOL-80 is delivered 
configured for your hardware. You can ignore the description of configuring the CRT 
given in Appendix A. Figure D-1 shows how to use the keyboard for entering data for a 
format 3 or 4 ACCEPT statement and the supervisor calls used for the functions of 
DISPLAY. COBOL-80 uses supervisor call number 8 for all output to the screen except 
for the cursor position function, which uses supervisor call number 10. 
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TRS-80 Model II Terminal 



I. Keyboard Input 








Input Code 


Key Label 


A. Editing Keys 














1. Line delete/Field delete 






15 




CONTROL 


2. Character delete 








08 




BACK SP/fl 


3. Forward Space 








ID 




— * 


4. Back Space 








IC 




i — 


5. Plus Sign 








2B 




+ 


6. Minus Sign 








2D 




— 


B. Terminator Keys 




Escape 


Code 


Input Code 


Key Label 


1. Backtab 






99 




IE 


T 


2. Escape 






01 




IB 


ESC 


3. Field terminators 






00 








a. Tab 










09 


TAB 


b. Carriage Return 










OD 


ENTER 


c. Line Feed 










IF 


I 


C. Function Keys 


Escape 


Code Input Code 


Key Label 


1. 




02 






01 


Fl 


2. 




03 






02 


F2 


II. Output Functions 








Supervisor Call 




A. Set Cursor Position 








SVC 10 B=row-l C=co 


1-1 DE=00 


B. Backspace Cursor 








SVC 8 B= 


=1C 




C. Cursor On 








SVC 8 B= 


=01 




D. Cursor Off 








SVC8B= 


=02 




E. Erase to End of Screen 








SVC 8 B= 


=18 




F. Erase to End of Line 








SVC8B= 


=17 




G. Sound Bell 








SVC8B: 


=07 




H. Set Highlight Mode 








SVC8B= 


=1A 




I. Reset Highlight Mode 








SVC 8 B= 


=19 





Figure D-1 
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D.2 ISIS-II 

D.2.1 Filename Descriptions 

File specifications for ISIS-II have the form 

:device:filename.extension 

The default extensions used in COBOL-80 command lines are: 

.COB for the source file 
.LST for the listing file 
.REL for the object file 

Executable files on the distribution disk and those created by L80 have no extension. The 
symbolic names for the console and printer are TTY: and LST: respectively. 

D.2. 2 Your Distribution Disk 

The ISIS COBOL-80 distribution disk contains the same files as a CP/M disk, except that 
the utility programs LIB and SEQCVT are not included. 



cobol-80 

reference 

manual 



Information in this document is subject to change without notice and does not represent a 
commitment on the part of Microsoft. The software described in this document is 
furnished under a license agreement or non-disclosure agreernent The software may be 
used or copied only in accordance with the terms of the agreement. 



(C) Microsoft, 1978, 1 979 , 1980 



To report software bugs or errors in the documentation, please complete and return the 
Problem Report at the back of this manual. 
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Microsoft COBOL is based upon American National Standard X3. 23-1974, 
Elements of the COBOL language are allocated to twelve different functional 
processing "modules.'* 

Each module of the COBOL Standard has two non-null "levels" — Level 1 
represents a subset of the full set of capabilities and features contained in Level 
2. 

In order for a given system to be called COBOL, it must provide at least Level! 
of the Nucleus, Table Handling and Sequential I-O Modules. 

The following summary specifies the content of Microsoft COBOL with respect 
to the Standard. 

Module Features of COBOL-80 

Nucleus All of Level 1, plus these features of Level 2: 

CONDITIONS: 

Level 88 conditions with value series or range 

Use of logical AND/OR/NOT in conditions 

Use of algebraic relational symbols «,>,=) 

Implied subject, or both subject and relation, in relational conditions. 

Sign Test 

Nested IF statements; parentheses in conditions 

VERBS: 

Extensions to the functions of ACCEPT and DISPLAY for formatted 

screen handling 

ACCEPT ance of data from DATE/DAY/TIME 

STRING and UNSTRING statements 

COMPUTE with multiple receiving fields 

PERFORM VARYING . . . UNTIL 

IDENTIRERS: 

Mnemonic-names for ACCEPT or DISPLAY devices 

Procedure-names consisting of digits only 

Qualification of names (in Procedure Division statements only) 



COBOL-aO Reference Manual 
Introduction 



Release 4 



Module 



Features 



Sequential 
Relative^ and 
Indexed I/O 



Sequential I/O 



Relative and 
Indexed I/O 



All of Level 1 plus these features of Level 2: 

RESERVE clause 

Multiple operands in OPEN & CLOSE, with individual 

options per file 

VALUE OF RLE-ID IS data-nanne 

EXTEND mode for OPEN 

WRITE ADVANCING data-name lines 

LINAGE phrase and AT END-OF^AGE clause 

DYNAMIC access mode (with READ NEXT) 

START (with key relationals EQUAL, GREATER, or 

NOT LESS) 



Library 

Inter-Proqram 
Communication 



Level 1 



Level 1 



Table Handling 



All of Level 1 

Full Level 2 formats for SEARCH statement 



Debugging Special extensions to ANSI-74 Standard 

convenient trace style debugging. 
Conditional Compilation: lines with "D in 
are bypassed unlesss *^VITH DEBUGGING 
given in SOURCE -COMPUTER paragraph. 



providing 

column 7" 
MODE" is 



Segmentation Level 1 
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CHAPTER 1 
Fundamental Concepts of COBOL 



1.1 Character Set 

The COBOL source language character set consists of the following characters: 

Letters A through Z 
Blank or space 
Digits through 9 
Special characters: 

+ Plus sign 

- Minus sign 

* Asterisk 

= Equal sign 

> Relational sign (greater than) 

< Relational sign (less than) 

$ Dollar sign 

, Comma 

; Semicolon 

. Period or decimal point 

" Quotation mark 

( Left parenthesis 

) Right parenthesis 

' Apostrophe (alternate quotation mark) 

/ Slash 

Of the previous set, the following characters are used for words: 

through 9 
A through Z 
- (hyphen) 



( Left parenthesis 
) Right parenthesis 
, Comma 
. Period 
: Semicolon 
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The following relation characters are used in simple conditions: 

> 

< 



In the case of non-numeric (quoted) literals, comment entries, and comment 
lines, the COBOL character set is expanded to^ Include the computer's entire 
character set. 



X.2 Punctuation 

The following general rules of punctuation apply in writing source programs: 

!• As punctuation, a period, semicolon, or comma should not be 

preceded by a space, but must be followed by a space. 

2. At least one space must appear between two successive words 
and/or literals. Two or more successive spaces are treated as a 
single space, except in non-numeric literals. 

3. Relation characters and arithmetic operators should always be 
preceded by a space and followed by another space. 

4. A comma may be used as a separator between successive operands 
of a statement, or between two subscripts. 

5. A semicolon or comma may be used to separate a series of 
statements or clauses. 



1.3 Word Formation 

User -defined and reserved words are composed of a combination of not more 
than 30 characters, chosen from the following set of 37 characters: 

through 9 (digits) 
A through Z (letters) 
- (hyphen) 
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All words must contain at least one letter or hyphen, except procedure-names 
which may consist entirely of digits. A word may not begin or end with a 
hyphen. A word is ended by a space or by proper punctuation. A word may 
contain more than one embedded hyphen; consecutive embedded hyphens are also 
permitted. All words are either reserved words, which have preassigned 
meanings, or programmer-supplied names. If a programmer-supplied name is not 
unique, there must be a unique method of reference to it by use of name 
qualifiers, e.g., TAX-RATE IN STATE-TABLE. Primarily, a non-reserved word 
identifies a data item or field and is called a data-name. Other cases of 
non-reserved words are file-names, condition-names, mnemonic-names, and 
procedure -nam es. 



1.4 Format (Notation 

Throughout this publication, "general formats" are prescribed for various clauses 
and statements to guide the programmer in writing his own statements. They 
are presented in a uniform system of notation, explained in the following 
paragraphs. 

1. All words printed entirely in capital letters are reserved words. 
These are words that have preassigned meanings. In all formats, 
words in capital letters represent actual occurrences of those words- 

2. All underlined reserved words are required unless the portion of the 
format containing them is itself optional. These are key words. If 
any key word is missing or is incorrectly spelled, it is considered an 
error in the program. Reserved words not underlined may be 
included or omitted at the option of the programmer. These words 
are optional words; they are used solely for improving readability of 
the program. 

3. The characters < > = (although not underlined) are required when 
present in statement formats. 

4. All punctuation and other special characters represent actual 
occurrences of those characters. Punctuation is essential where it 
is shown. Additional punctuation can be inserted, according to the 
rules for punctuation specified in Section 1.2. As separators, all 
commas, semicolons and periods must be followed by a space (or 
blank). 
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5, Words printed in lower-case letters in formats represent generic 
terms (e.g., data-names) for which the user must insert a valid entry 
in the source program- 

6, Any part of a statement or data description entry that is enclosed in 
square brackets ([ ]) is optional. Parts between matching braces ({ }) 
represent a choice of mutually exclusive options* 

7, Certain entries in the formats consist of a capitalized word(s) 
followed by the word "Clause" or "Statement*" These designate 
clauses or statements that are described in other formats, in 
appropriate sections of the text. 

a. In order to facilitate reference to lower-case words in the 

explanatory text, some of them are followed by a hyphen and a digit 
or letter. This modification does not change the syntactical 
definition of the word. 

9. Alternate options may be indicated by separating the mutually 
exclusive choices by a vertical stroke, e.g.: 

AREA I AREAS is equivalent to j AREA ] 

I AREAS J 

10. The ellipsis (...) indicates that the immediately preceding unit may 
occur once, or any number of times in succession. A unit means 
either a single lower-case word, or a group of lower-case words and 
one or more reserved words enclosed in brackets or braces. If a 
term is enclosed in brackets or braces, the entire unit of which it is 
part must be repeated when repetition is specified. 

11. Optional elements may be indicated by parentheses instead of 
brackets, provided the lack of formality represents no substantial 
bar to clarity. 

12. Comments, restrictions, and clarification on the use and meaning of 
every format are contained in the appropriate sections of this 
manual. 
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1. 5 Level Numbers and Data^Names 

For purposes of processing, the contents of a file are divided into logical records, 
with level number 01 initiating a logical record description. Subordinate data 
items that constitute a logical record are grouped in a hierarchy and identified 
with level numbers 02 to 49, not necessarily consecutive. Additionally, level 
number 77 identifies a "stand alone" item in Working Storage or Linkage Sections; 
that is, it does not have subordinate elementary items as does level 01. Level 88 
is used to define condition-names and associated conditions. A level number less 
than 10 may be written as a single digit. 

Levels allow specification of subdivisions of a record necessary for referring to 
data. Once a subdivision is specified, it may be further subdivided to permit 
more detailed data reference. This is illustrated by the following weekly 
timecard record, which is divided into four major items: name, 
employee-number, date and hours, with more specific information appearing for 
name and date. 



TIME-CARO 



NAME 




LAST-NAME 

FIRST-INIT 

MIDDLE-INIT 



EMPLOYEE-NUM 

WEEKS-END-DATE 
HOURS-WORKED 



^ 



MONTH 

DAY-NUMBER 

YEAR 



Subdivisions of a record that are not themselves further subdivided are called 
elementary items. Data items that contain subdivisions are known as group 
items. When a Procedure Division statement makes reference to a group item, 
the reference applies to the area reserved for the entire group. All elementary 
items must be described with a PICTURE or USAGE IS INDEX clause. 
Consecutive logical records (01) subordinate to any given file represent implicit 
redefinitions of the same area whereas in the Working-Storage section, each 
record (01) is the definition of its own memory area. 

Less inclusive groups are assigned numerically higher level numbers. Level 
numbers of items within groups need not be consecutive. A group whose level is 
k includes all groups and elementary items described under it until a level 
number less than or equal to k is encountered. 

Separate entries are written in the source program for each level. To illustrate 
level numbers and group items, the weekly timecard record in the previous 
example may be described by Data Division entries having the following level 
numbers, data-names and PICTURE definitions. 
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01 TIME-CARD. 
02 NAME. 

03 LAST-NAME PICTURE X(18), 

03 FIRST-INIT PICTURE X. 

03 MIDDLE-INIT PICTURE X. 

02 EMPLOYEE-NUM PICTURE 99999. 
02 WEEKS-END-DATE. 

05 MONTH PIC 99. 

05 DAY-NUMBER PIC 99. 

05 YEAR PIC 99. 

02 HOURS-WORKED PICTURE 99 V 9. 

A data-name is a word assigned by the user to identify a data item used in a 
program. A data-name always refers to a region of data, not to a particular 
value. The item referred to often assumes a number of different values during 
the course of a program. 

A data-name must begin with an alphabetic character. A data-name or the key 
word FILLER must be the first word following the level number in each Record 
Description entry, as shown in the following general format: 

level number f data-name 

(FILLER 

This data-name is the defining name of the entry and is used to refer to the 
associated data area (containing the value of a data item). 

If some of the characters in a record are not used in the processing steps of a 
program, then the data description of these characters need not include a 
data-name. In this case, FILLER is written in lieu of a data-name after the level 
number. 



1.6 File Names 

A file is a collection of data records, such as a printed listing or a region of 
floppy disk, containing individual records of a similar class or application, A 
file-name is defined by an FD entry in the Data Division's File Section. FD is a 
reserved word which must be followed by a unique programmer-supplied word 
called the file-name. Rules for composition of the file-name word are identical 
to those for data-names (see Section 1.3). References to a file-name appear in 
the Procedure Division statements OPEN, CLOSE and READ, as well as in the 
Environment Division. CAUTION: File names are not to be confused with file 
ID'S as described in Section 3.14.2. 
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i-7 Condi tion-Nanrtes 

A condition-name is defined in level 88 entries within the Data Division. It is a 
name assigned to a specific value, set or range of values, within the complete set 
of values that a data item may assume. Rules for formation of name words are 
specified in Section 1.3. Explanations of condition-name declarations and 
procedural statements employing them are given in the chapters devoted to the 
Data and Procedure Divisions. 



1.3 Mnemonic-Names 

A mnemonic-name is assigned in the Environment Division for reference in 
ACCEPT or DISPLAY statements. It assigns a user-defined word to an 
implemen tor-chosen name, such as PRINTER. A mnemonic-name is composed 
according to the rules in Section 1.3. 



1.9 Literals 

A literal is a constant that is not identified by a data-name in a program. A 
literal is either non-numeric or numeric. 

Non-Numeric Literals 

A non-numeric literal must be bounded by matching quotation marks (or 
apostrophes) and may consist of any combination of characters in the ASCII set, 
except quotation marks (or apostrophe). All spaces enclosed by the quotation 
marks are included as part of the literal. A non-numeric literal must not exceed 
120 characters in length. 

The following are examples of non-numeric literals: 

"ILLEGAL CONTROL CARD'* 

'CHARACTER -STRING' 

"DO'S & DON'PS" 

Each character of a non-numeric literal (following the introductory delimiter) 
may be any character other than the delimiter. That is, if the literal is bounded 
by apostrophes, then quotation (") marks may be included within the literal, and 
vice versa . Length of a non-numeric literal excludes the delimiters; minimum 
length is one. 
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A succession of two "delimiters" within a literal is interpreted as a single 
representation of the delimiter within the literal. 

Non-numeric literals may be "continued" from one line to the next. When a 
non-numeric literal is of a length such that it cannot be contained on one line of 
a coding sheet, the following rules apply to the next line of coding (continuation 
line): 

1. A hyphen is placed in column 7 of the continuation line. 

2. A delimiter is placed in Area B preceding the continuation of the 
literal. 

3. All spaces at the end of the previous line and any spaces following 
the delimiter in the continuation line and preceding the final 
delimiter of the literal are considered to be part of the literal. 

4. On any continuation line, Area A should be blank. 

Numeric Literals 

A numeric literal must contain at least one and not more than 18 digits. A 
numeric literal may consist of the characters through 9 (optionally preceded by 
a sign) and the decimal point. It may contain only one sign character and only 
one decimal point. The sign, if present, must appear as the leftmost character in 
the numeric literal. If a numeric literal is unsigned, it is assumed to be positive. 

A decimal point may appear anywhere within the numeric literal, except as the 
rightmost character. If a numeric literal does not contain a decimal point, it is 
considered to be an integer. 

The following are examples of numeric literals: 

72 4.1011 3.14159 -6 -.333 0.5 

By use of the Environment Division specification DECIMAL-POINT IS COMMA, 
the functions of the characters period and comma are interchanged, putting the 
"European" notation into effect. In this case, the value of "pi" would be 3,1416 
when written as a numeric literal. 
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1.10 Figurative Constants 

A figurative constant is a special type of literal- It represents a value to which a 
standard name has been assigned. A figurative constant is not bounded by 
quotation marks. 

ZERO may be used in many places in a program as a numeric literal. Other 
figurative constants are available to provide non-numeric data; the reserved 
words representing various characters are as follows: 

SPACE the blank character represented by '*octal" 40 

LOW- VALUE the character whose "octal" representation is 00 

HIGH- VALUE the character whose "octal" representation is 177 

QUOTE the quotation mark, whose "octal" representation is 42 

ALL literal one or more instances of the literal, which must be a 

one-character non-numeric literal or a figurative 
constant, in which case ALL is redundant but serves for 
readability. 

The plural forms of these figurative constants are acceptable to the compiler but 
are equivalent in effect. A figurative constant represents as many instances of 
the associated character as are required in the context of the statement. 

A figurative constant may be used anywhere a literal is called for in a "general 
format" except that whenever the literal is restricted to being numeric, the only 
figurative constant permitted is ZERO. 



1.11 Structure of a Program 

Every COBOL source program is divided into four divisions. Each division must 
be placed in its proper sequence, and each must begin with a division header. 

The four divisions, listed in sequence, and their functions are: 

IDENTIFICATION DIVISION, which names the program. 

ENVIRONMENT DIVISION, which indicates the computer equipment and 
features to be used in the program. 

DATA DIVISION, which defines the names and characteristics of data to 
be processed. 

PROCEDURE DIVISION, which consists of statements that direct the 
processing of data at execution time- 
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It is very difficult for COBOL to compile source code if the Division headers are 
omitted, misspelled, or are accidentally commented out. In this case, 
unpredictable events may occur. 

The following skeletal coding defines program component structure and order. 
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IDENTIFICATION DIVISION . 

PROGRAM-ID . program-name. 

[ AUTHOR , comment-entry ...] 

[INSTALLATION , comment-entry ...] 

[ DATE -WRITTEN , comment-entry ...] 

[ DATE -COMPILED , comment-entry ...] 

[ SECURITY , comment-entry ...] 

ENVIRONMENT DIVISION . 

[ CONFIGURATION SECTION . 

[ SOURCE -COMPUTER , entry] 

[ OBJECT-COMPUTER , entry] 

[ SPECIAL-NAMES , entry] ] 

[INPUT-OUTPUT SECTION . 

FILE-CONTROL , entry ... 

[I-O-CONTROL . entry ...] ] 

DATA DIVISION . 

[FILE SECTION. 

[file description entry 

record description entry ...]...] 

[ WORKING-STORAGE SECTION . 

[data item description entry ...]...] 

[ LINKAGE SECTION . 

[data item description entry ...]...] 

[ SCREEN SECTION . 

[screen-description-entry .-.] ...] 

PROCEDURE DIVISION [ USING [identifier-1] ...]. 

[ DECLARATIVES . 

[section-name SECTION . USE Sentence. 

[paragraph-name, [sentence]...]...]... 

END DECLARATIVES .] 

[[section-name SECTION , [segment number]] 

[paragraph-name, [sentence]...]...]... 
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1.12 Coding Rules 

Since Microsoft COBOL is a subset of American National Standards Institute 
(ANSI) COBOL, programs may be written on standard COBOL coding sheets, and 
the following rules are applicable- 

1. Each line of code should have a six-digit sequence number in 
columns 1-6, such that the punched cards are in ascending order. 
Blanks are also permitted in columns 1-6. 

2. Reserved words for division, section, and paragraph headers must 
begin in Area A (columns 3-11). Procedure-names must also appear 
in Area A (at the point where they are defined). Level numbers may 
appear in Area A. Level numbers 01, 77 and level indicator "FD" 
must begin in Area A. 

3. All other program elements should be confined to columns 12-72, 
governed by the other rules of statement punctuation. 

4. Columns 73-80 are ignored by the compiler. Frequently, these 
columns are used to contain the deck identification. 

5. Explanatory comments may be inserted on any line within a source 
program by placing an asterisk in column 7 of the line. The line will 
be produced on the source listing but serves no other purpose. If a 
slash (/) appears in column 7, the associated card is treated as 
comments and will be printed at the top of a new page when the 
compiler lists the program. 

6. Any program element may be "continued" on the following line of a 
source program. The rules for continuation of a non-numeric 
("quoted") literal are explained in Section 1.9. Any other word or 
literal or other program element is continued by placing a hyphen in 
the column 7 position of the continuation line. The effect is 
concatenation of successive word parts, exclusive of all trailing 
spaces of the last predecessor word and ail leading spaces of the 
first successor word on the continuation line. On a continuation 
line, Area A must be blank. 

7. Any tab characters in a line are expanded as if there were tab stops 
at every eighth column past column 1, except that the first tab stop 
is in column 7, just past the six sequence-number columns. 
Subsequent tab stops are columns 17, 25, 33, etc. as determined by 
the general rule. 



CO8OL-80 Reference Manual - Release 4 15 

Fundamental Concepts of COBOL 



1*^^ Qualification of Names 

When a data-name, condition-name or paragraph name is not unique, reference 
thereto may be accomplished uniquely by use of qualifier names. For example, if 
there were two or more items named YEAR, the qualified reference 

YEAR OF HIRE-DATE 

might differentiate between YEAR fields in KRE-DATE and 
TERMINATION-DATE. 

Qualifiers are preceded by the word OF or IN; successive data-name or 
condition-name qualifiers must designate lesser-level-numbered groups that 
contain all preceding names in the composite reference, i.e., HIRE-DATE must 
be a group item (or file-name) containing an item called YEAR. 
Paragraph-names may be qualified by a section-name. The maximum number of 
qualifiers is five. File-names and mnemonic-names must be unique. 

A qualified name may only be written in the Screen Section or Procedure 
Division. A reference to a multiply-defined paragraph-name need not be 
qualified when referred to from within the same section. 



1.14 COPY Statement 

The COPY statement is used to logically embed the text of a disk file (other 
than the source file) in the source code input to the COBOL-80 compiler. The 
format of the COPY statement is: 

COPY text-name 

where text-name is a disk file name in the format required by the operating 
system in use. For example, suppose BDEF.COB is a text file containing the 
following source code: 

05 B. 

10 Bl PIC X. 
10 B2 PIC X. 



COBOL-80 Reference Manual - Release 4 16 

Fundamental Concepts of COBOL 



Then a source file containing 

05 A. 

10 Al PIC 9. 
COPY BDEF.COB 
05 C. 

10 CI PIC 2. 



will compile exactly as if the following had been coded: 

05 A. 

10 Al PIC 9. 
05 B. 

10 Bl PIC X. 

10 B2 PIC X. 
05 C. 

10 CI PIC Z. 

The portion of a source line containing a COPY statement must contain only 
spaces from the end of text-name to the end of the line. 
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2.1 Identification Division 

Every COBOL program begins with the header: IDENTIFICATION DIVISION. 
This division is divided into paragraphs having preassigned names: 

PROGRAM-ID. program-name. 

AUTHOR. comments. 

INSTALLATION. comments. 

DATE-WRITTEN. comments. 

DATE-COMPILED. comments. 

SECURITY. comments. 

Only the PROGRAM-ID paragraph is required, and it must be the first 
paragraph. Program-name is any alphanumeric string of characters, the first of 
which must be alphabetic. Only the first 6 characters of program-name are 
retained by the compiler. The program-name identifies the object program and 
is contained in headings on compilation listings. 

The contents of any other paragraphs are of no consequence, serving only as 
documentary remarks. 



2.2 Environment Division 

The Environment Division specifies a standard method of expressing those 
aspects of a COBOL program that are dependent upon physical characteristics of 
a specific computer. It is required in every program. 
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The general fornnat of the Environment Division is: 

ENVIRONMENT DIVISION . 

CONFIGURATION SECTION . 

SOURCE-COMPUTER . Computer -name [WITH DEBUGGING MODE ]. 

OBJECT-COMPUTER . Computer-name 

[ MEMORY SIZE integer WORDS I CHARACTERS I MODULES ] 
[PROGRAM COLLATING SEQUENCE IS ASCIIJ . 

SPECIAL-NAMES. [ PRINTER IS mnemonic-name] ASCII IS / STANDARD-I 

NATIVE 
[ CURRENCY SIGN IS literal] ^ 

[ DECIMAL-POINT IS COMMA ]. 

INPUT-OUTPUT SECTION. 



FILE -CONTROL , {file-control-entry}... 
I-0-CONTROL. 

RECORD 



[SAME 



SORT 



SORT-MERGE 



AREA FOR file-name...]... 



2.2.1 CONFIGURATION SECTION 

The CONFIGURATION SECTION, which has three possible paragraphs, is 
optional. The three paragraphs are SOURCE-COMPUTER, 

OBJECT-COMPUTER, and SPECIAL- NAMES. The contents of the first two 
paragraphs are treated' as commentary, except for the clause WITH DEBUGGING 
MODE, if present (see Section 4.22). The third paragraph, SPECIAL-NAMES, 
relates implementor names to user-defined names and changes default editing 
characters. The PRINTER IS phrase allows definition of a name to be used in the 
DISPLAY statement with UPON. 

If the currency symbol is not desired to be the dollar sign, the user may specify a 
single character non-numeric literal in the CURRENCY SIGN clause. However, 
the designated character may not be a quote mark, nor any of the characters 
defined for PICTURE representations, nor digits (0-9). 

The "European" convention of separating integer and fraction positions of 
numbers with the comma character is specified by employment of the clause 
DECIMAL-POINT IS COMMA. 
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Note that the reserved word IS is required in entries for currency sign definition 
and decimal-point convention specification. 

The entry ASCII IS NATIVE/STANDARD-1 specifies that data representation 
adheres to the American Standard code for Information Interchange. However, 
this convention is assumed even if the ASCII-entry is not specifically present. In 
this compiler, NATIVE and STANDARD-1 are identical, and refer to the 
character set representation specified in Appendix IV. 



2.2.2 INPUT-OUTPUT SECTION 

The second section of the Environment Division is mandatory unless the program 
has no data files; it begins with the header: 

INPUT-OUTPUT SECTION. 



This section has two paragraphs: FILE-CONTROL and I-O-CONTROL. In this 
section, the programmer defines the file assignment parameters, including 
specification of buffering. 

2.2.2.1 FILE-CONTROL ENTRY (SELECT ENTRY) 

For each file having records described in the Data Division's File Section, a 
Select Sentence-Entry (beginning with the reserved word SELECT) is required in 
the FILE-CONTROL paragraph. The format of a Select Sentence-Entry for a 
sequential file is: 

SELECT file-name ASSIGN TO DISK I PRINTER 

[ RESERVE integer AREAS I AREA] 

[FILE STATUS IS data-name-1] 

[ ACCESS MODE IS SEQUENTIAL ] [ ORGANIZATION IS [ LINE ] SEQUENTIAL ]. 

The SELECT entry must begin to the right of Area A of the source line. All 
phrases after "SELECT filename" can be in any order. Both the ACCESS and 
ORGANIZATION clauses are optional for regular sequential input-output 
processing. For Indexed or Relative files, alternate formats are available for this 
section, and are explained in the chapters on Indexed and Relative files. 
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Two formats are available for sequential disk files* One is the regular form 
whidi is requested by ORGANIZATION IS SEQUENTIAL, and the other Is 
requested by ORGANIZATION IS LINE SEQUENTIAL. Both forms assume the 
records in the file are variable-length. The regular sequential organization is 
that of a two-byte count of the record length followed by the actual record, for 
as many records as exist in the file. The line sequential organization has the 
record followed by a carriage return/line feed delimiter, for as many records as 
exist in the file* No COMP or COMP-3 information should be written into a Line 
Sequential file because these data items may contain the same binary codes used 
for carriage return and line feed which therefore would cause a problem when 
subsequently reading the file. Both organizations pad any remaining space of the 
last physical block with Control-Z characters, indicating end-of-file. All records 
are placed in the file with no gaps; they span physical block boundaries. 

The RESERVE clause is not functional in COBOL-80, but is scanned for correct 
syntax. One physical block buffer is always allocated to the logical record area 
assigned to it. This allows logical records to be spanned over physical block 
boundaries. For files assigned to PRINTER, the logical record area is used as the 
physical buffer as well. 

In the FILE STATUS entry, data-name-1 must refer to a two-character 
Working-Storage or Linkage Section item of category alphanumeric into which 
the run-time data management facility places status information after an I-O 
statement. The left-hand character of data-name-1 assumes the values: 

*0' for successful completion 

'1* for end-of-file 

'2' for invalid key (only for indexed and relative files) 

'3* for a non-recoverable I-O error 

The right-hand character of data-name-1 is set to '0* if no further status 
information exists for the previous I-O operation. The following combinations of 
values are possible: 

File Status Left File Status Right Meaning 

»0' '0' O.K. 

'V '0' EOF 

*3* '0' Permanent error 

'3' '4' Disk space full 



iqt 



File damaged 



In an OPEN INPUT or OPEN I-O statement, a File Status of OO' means 'File Not 
Found.' 

For values of status-right when status-left has a value of '2% see the chapters on 
Indexed or Relative files. 
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2.2.2.2 I^>CONTROL PARAGRAPH 

The SAME AREA clause is optional. Only the SAME RECORD AREA form is 
functional in COBOL-80. The other forms are checked for correct syntax but do 
not cause any sharing of physical buffer space. 

The SAME RECORD AREA form causes all the named files to share the same 
logical record area in order to conserve memory space. 

The format of the SAME AREA entry is: 

RECORD 



SAME 



SORT 



SORT-MERGE 



AREA FOR filename... 



All files named in .a given SAME AREA clause need not have the same 
organization or access. However, no file may be listed in more than one SAME 
AREA clause. 

The SORT and SORT-MERGE options are allowed only in those versions of 
COBOL-SO supporting the SORT facility. 
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The Data~ Division, which is one of the required divisions in a progrann, is 
subdivided into four sections: File Section, Working-Storage Section, Linkage 
Section, and Screen Section. Each is discussed in Sections 3,13-3-16, but first, 
aspects of data specification that apply in all sections will be described. 



3.1 Data Items 

Several types of data items can be described in COBOL programs. These data 
items are described in the following paragraphs. 

3.1.1 Group Items 

A group item is defined as one having further subdivisions, so that it contains one 
or more elementary items. In addition, a group item may contain other groups. 
An item is a group item if, and only if, its level number is less than the level 
number of the immediately succeeding item. If an item is not a group item, then 
it is an elementary item. Ordinarily, the maximum size of any data item is 4095 
bytes. In order to allow tables to exceed this limit, however, level 01 group 
items are not checked for length. Such an item longer than 4095 bytes will be 
disallowed by the compiler as an operand of a Procedure Division statement such 
as MOVE, INSPECT, etc. 



3,1.2 Elementary Items 

An elementary item is a data item containing no subordinate items. 

Alphanumeric Item; An alphanumeric item consists of any combination of 
characters, making a "character string" data field. If the associated picture 
contains "editing" characters, it is an alphanumeric edited item. 

Report (Edited) Item ; A report item is an edited "numeric" item containing only 
digits and/or special editing characters. It must not exceed 30 characters in 
length. A report item can be used only as a receiving field for numeric data. It 
is designed to receive a numeric item but cannot be used as a numeric item itself. 
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3.1.3 Numeric Items 

Numeric items are elementary items intended to contain numeric data only. 

External Decimal Item ; An external decimal data item is an item in whicli one 
character (byte) is employed to represent one digit. A maximum number of 18 
digits is permitted; the exact number of digit positions is defined by writing a 
specific number of 9-characters in the PICTURE description. For example, 
PICTURE 999 defines a 3-digit item. That is, the maximum decimal value of the 
item is nine hundred ninety-nine. 

If the PICTURE begins with the letter S, then the item also has the capability of 
containing an "operational sign." An operational sign does not occupy a separate 
character (byte), unless the "SEPARATE" form of SIGN clause is included in the 
item's description. Regardless of the form of representation of an operational 
sign, its purpose is to provide a sign that functions in the normal algebraic 
manner. 

The USAGE of an external decimal item is DISPLAY (see USAGE clause. Section 
3.4). 

Internal Decimal Item : An internal decimal item is stored in packed decimal 
format. It is attained by inclusion of the CGMPUTATIONAL-3 USAGE clause. 

A packed decimal item defined by n 9'3 in its PICTURE occupies 1/2 of (n + 2) 
(rounded down) bytes in memory. All bytes except the rightmost contain a pair 
of digits, and each digit is represented by the binary equivalent of a valid digit 
value from to 9. The item's low order digit and the operational sign are found 
in the rightmost byte of a packed item. For this reason, the compiler considers a 
packed item to have an arithmetic sign, even if the original PICTURE lacked an 
S-character. 

Binary Item : A binary item uses the base 2 system to represent an integer in the 
range -32768 to 32767. It occupies one 16-bit word. The leftmost bit of the 
reserved area is the operational sign. A binary item is specified by USAGE IS 
COMPUTATIONAL. 

Index-Data-Item : An index-data-item has no PICTURE; it is defined by the 
USAGE IS INDEX clause. (Refer to Chapter 6, "Table Handling by the Indexing 
Method-") 
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3.2 DATA DESCRIPTION ENTRY 

A Data Description entry specifies the characteristics of each field (item) in a 
data record. Each item must be described in a separate entry in the same order 
in which the items appear in the record. Each Data Description entry consists of 
a level number, a data-name, and a series of independent clauses followed by a 
period. The general format of a Data Description entry is: 



level-number 



{ data-name) 
FILLER j (REDEFINES-clause) (JUSTIFIED-clause) 



(PICTURE-ciause) (USAGE-clause) (SYNCHRONIZED-cIause) 

(OCCURS-clause) (BLANK -clause) ( V ALUE-clause) (SIGN-clause). 

When this format is applied to specific items of data, it is limited by the nature 
of the data being described. .The format allowed for the description of each data 
type appears below. Clauses that are not shown in a format are specifically 
forbidden in that format. Clauses that are mandatory in the description of 
certain data items are shown without parentheses. The clauses may appear in 
any order except that a REDEFINES-clause, if used, should come first. 

Group Item Format 

(data-name) 
level-number [ FILLER j (REDEFINES-clause) (USAGE-clause) 

(OCCURS-clause) (VALUE clause) (SIGN-clause). 

Example: 

01 GROUP-NAME. 

02 FIELD-8 PICTURE X. 
02 FIELD-C PICTURE X. 



NOTE 

The USAGE clause may be 
a group level to avoid 
writing of it at the 
element level. 


written at 

repetitious 

subordinate 



CO8OL-80 Reference Manual - Release 4 25 

Data Division 



3.3 FORMATS FOR ELEMENTARY ITEMS 
ALPHANUMERIC ITEM (also called a character-string item) 

{data-name 1 
FILLER ) (REDEFINES-clause) (OCCURS-clause) 

PICTURE IS an-form (USAGE IS DISPLAY ) (JUSTIFIED-clause) 

( VALUE IS non-numeric-literal) (SYNCHRONIZED-ciause), 

Examples: 

02 MISC-1 PIC X(53). 

02 MISC-2 PICTURE BXXXBXXB. 



REPORT ITEM (also called a numeric-edited item) 

(data-name I 
level-number | FILLER j (REDERNES-clause) (OCCURS-clause) 

PICTURE IS report-form ( BLANK WHEN ZERO ) (USAGE IS DISPLAY ) 

( VALUE IS non-numeric-literai) (SYNCHRONIZED-ciause). 

Example: 

02 XTOTAL PICTURE $999,999.99-. 

DECIMAL ITEM 

I data-name I 
level-number \ FILLER j (REDEFINES-clause) (OCCURS-clause) 

PICTURE IS numeric-form (SIGN-clause) 

(US AGE -clause) ( VALUE IS numeric-literal) (SYNCHRONIZED-ciause). 

Examples: 

02 HOURS-WORKED PICTURE 99V 9, USAGE IS DISPLAY. 
02 HOURS-SCHEDULED PIC S99V9, SIGN IS TRAILING. 



11 TAX-RATE PIC S99V999 VALUE 1.375, COMPUTATIONAL-3. 
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BINARY ITEM 

I data-name 
level-number \ FILLER f (REDEFINES-clause) (OCCURS-clause) 

PICTURE IS numeric-form 

USAGE IS COMPUTATIONAL I COMP I INDEX 

(VALUE IS numeric-llteral) (SYNCHRONIZED-clause). 



NOTE 

A PICTURE or VALUE must not be 
given for an INDEX Data Item. 



Examples: 



02 SUBSCRIPT PICTURE 999 COMP, V ALUE ZERO. 
02 YEAR-TO-DATE PIC S9(5) COMPUTATIONAL. 



3.4 USAGE CLAUSE 

The USAGE clause specifies the form in which data is represented. 

The USAGE clause may be written at any level. If USAGE is not specified, the 
item is assumed to be in "DISPLAY" mode. The general format of the USAGE 
clause is: 

^ COMPU TATIONAL 
USAGE IS j INDEX 

DISPLAY 
COMPUTATIONAL-3 

INDEX is explained in Chapter 6, Table Handling. COMPUTATIONAL, which 
may be abbreviated COMP, usage defines an integer binary field. 
COMPUTATIONAL-3, which may be abbreviated COMP-3, defines a packed 
(internal decimal) field. 

If a USAGE clause is given at a group level, it applies to each elementary item in 
the group. The USAGE clause for an elementary item must not contradict the 
USAGE clause of a group to which the item belongs. 
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3,5 PICTURE CLAUSE 

The PICTURE clause specifies a detailed description of an elementary level data 
itenn and may include specification of special report editing. The reserved word 
PICTURE may be abbreviated PIC. 

The general format of the PICTURE clause is: 

Ian-form \ 

numeric-formi 
report -form J 

There are three possible types of pictures: An-form, Numeric-form and 
Report-form, 

An-Form Option ; This option applies to alphanumeric (character string) items. 
The PICTURE of an alphanumeric item is a combination of data description 
characters X, A or 9 and editing characters B, and /• An X indicates that the 
character position may contain any character from the computer's ASCII 
character set. A PICTURE that contains at least one of the combinations: 



(a) 


A and 9, or 


(b) 


X and 9, or 


(c) 


X and A 



in any order is considered as if every 9, A or X character were X. The 
characters B, and / may be used to insert blanks or zeros or slashes in the 
item. This is then called an alphanumeric-edited item. 

If the string has only A's and B*s, it is considered alphabetic; if it has only 9's, it 
is numeric (see below). 

Numeric-Form Option ; The PICTURE of a numeric item may contain a valid 
combination of the following characters: 

9 The character 9 indicates that a digit position which must contain a 

numeric character. The maximum number of 9's in a PICTURE is 18. 
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V The optional character V indicates the position of an assumed 

decimal point. Since a numeric item cannot contain an actual 
decimal point, an assumed decimal point is used to provide the 
compiler with information concerning the scaling alignment of items 
involved in computations. Storage is never reserved for the 
character V. Only one V is permitted in any single PICTURE. 

S The optional character S indicates that the item has an operational 

sign. It must be the first character of the PICTURE. See also, SIGN 
clause, Section 3.12. 

P The character P indicates an assumed decimal scaling position. It is 

used to specify the location of an assumed decimal point when the 
point is not within the number that appears in the data item. The 
scaling position character P is not counted in the size of the data 
item; that is, memory is not reserved for these positions. However, 
scaling position characters are counted in determining the maximum 
number of digit positions (18) in numeric edited items or in items 
that appear as operands in arithmetic statements. The scaling 
position character P may appear only to the left or right of the 
other characters in the string as a continuous string of P's within a 
PICTURE description. The sign character S and the assumed decimal 
point V are the only characters which may appear to the left of a 
leftmost string of P's. Since the scaling position character P implies 
an assumed decimal point (to the left of the P's if the P's are 
leftmost PICTURE characters and to the right of the Ps if the P's 
are rightmost PICTURE characters), the assumed decimal point 
symbol V is redundant as either the leftmost or rightmost character 
within such a PICTURE description. 

Report-Form Option ; This option describes a data item suitable as an "edited" 
receiving field for presentation of a numeric value. The editing characters that 
may be combined to describe a report item are as follows: 

9 V . Z CR DB , $ 4. * B - P / 

The characters 9, P and V have the same meaning as for a numeric item. The 
meanings of the other allowable editing characters are described as follows: 
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The decimal point character specifies that an actual decimal point 
is to be inserted in the indicated position and the source item is to 
be aligned accordingly* Numeric character positions to the right of 
an actual decimal point in a PICTURE must consist of characters of 
one type* The decimal point character must not be the last 
character in the PICTURE character string. PICTURE character 'P' 
may not be used if *.' is used. 

Z The characters Z and * are called * replacement characters. Each 

one represents a digit position. During execution, leading zeros to be 
placed in positions defined by Z or * are suppressed, becoming blank 
or *. Zero suppression terminates upon encountering the decimal 
point (• or V) or a non-zero digit. All digit positions to be modified 
must be the same (either Z or *), and contiguous starting from the 
left. Z or * may appear to the right of an actual decimal point only 
if aU digit positions are the same. 

CR DB CR and DB are called credit and debit symbols and may appear only 
at the right end of a PICTURE. These symbols occupy two character 
positions and indicate that the specified symbol is to appear in the 
indicated positions if the value of a source item is negative. If the 
value is positive or zero, spaces will appear instead. The PICTURE, 
CR, DB, +, and - symbols are mutually exclusive. 

, The comma specifies insertion of a comma between digits. Each 

insertion character is counted in the size of the data item, but does 
not represent a digit position. The comma may also appear in 
conjunction with a floating string, as described below. It must not be 
the last character in the PICTURE character string. 

A floating string is defined as a leading, continuous series of one of either $ or + 
or -, optionally interrupted by one or more insertion commas and/or decimal 
points. For example: 
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A floating string containing N + 1 occurrences of $ or + or - defines N digit 
positions. When moving a numeric value into a report item, the appropriate 
character floats from left to right, so that the developed report item has exactly 
one actual $ or + or - immediately to the left of the most significant nonzero 
digit, in one of the positions indicated by $ or -h or in the PICTURE. Blanks are 
placed in ail character positions to the left of the single developed $ or + or -• If 
the most significant digit appears in a position to the right of positions defined 
by the floating string, then the developed item contains $ or + or in the 
rightmost position of the floating string, and non-significant zeros may follow. 
The presence of an actual or implied decimal point in a floating string is treated 
as if all digit positions to the right of the point were indicated by the PICTURE 
character 9. In the following examples, b represents a blank in the developed 
items. 

PICTURE Numeric Value Developed Item 

$$$999 14 bb$014 

$$$$$$ 14 bbb$14 

«,™,999 -456 bbbbbb-456 

A floating string need not constitute the entire PICTURE of a report item, as 
shown in the preceding examples. Restrictions on characters that may follow a 
floating string are given later in the description. 

When a comma appears to the right of a floating string, the string character 
floats through the comma in order to be as close to the leading digit as possible. 

+ - The character + or - may appear in a PICTURE either singly or in a 
floating string. As a fixed sign control character, the + or - must 
appear as the last symbol in the PICTURE. The plus sign indicates 
that the sign of the item is indicated by either a plus or minus sign 
placed in the character position, depending on the algebraic sign of 
the numeric value placed in the report field. The minus sign 
indicates that blank or minus is placed in the character position, 
depending on whether the algebraic sign of the numeric value placed 
in the report field is positive or negative, respectively. 

8 Each appearance of B in a PICTURE represents a blank in the final 

edited value. 

/ Each slash in a PICTURE represents a slash in the final edited value. 

Each appearance of in a PICTURE represents a position in the 

final edited value where the digit zero will appear. 
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Other rules for a report (edited) item PICTURE are: 

1. The appearance of one type of floating string precludes any other 
floating string. 

2. There must be at least one digit position character, 

3. The appearance of a floating sign string or fixed plus or minus 
insertion character precludes the appearance of any other of the 
sign control insertion characters, namely +, -, CR, DB- 

4. The characters to the right of a decimal point up to the end of a 
PICTURE, excluding the fixed insertion characters +, -, CR, DB (if 
present), are subject to the following restrictions: 

a. Only one type of digit position character may appear. That 
is, Z, *, 9, and floating-string digit position characters $, +, -, 
are all mutually exclusive, 

b. If one of the numeric character positions to the right of a 
decimal point is represented by + or - or $ or Z, then all the 
numeric character positions in the PICTURE must be 
represented by the same character. 

5. The PICTURE character 9 can never appear to the left of a floating 
string, or replacement character. 

Additional notes on the PICTURE Clause: 

1. A PICTURE clause must only be used at the elementary level. 

2. An integer enclosed in parentheses and following X9$ZP*B-or 
-I- indicates the number of consecutive occurrences of the PICTURE 
character. 

3. Characters V and P are not counted in the space allocation of a 
data item. CR and DB occupy two character positions each. 

4. A maximum of 30 character positions is allowed in a PICTURE 
character string. For example, PICTURE X(89) consists of five 
PICTURE characters. 

5. A PICTURE must contain at least one of the characters A, Z, *, X, 
or 9, or at least two consecutive appearances of the -r or - or $ 
characters. 
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The characters 
PICTURE. 



S, V, CR, and DB can appear only once in a 



7. When DECIMAL-POINT IS COMMA is specified, the explanations for 

period and comma are understood to apply to comma and period, 
respectively. 

The examples below illustrate the use of PICTURE to edit data. In each 
example, a movement of data is implied, as indicated by the column headings. 
(Data value shows contents in storage; scale factor of this source data area is 
given by the PICTURE.) 



Source Area 


Receiving Area 


PICTURE 


Data 
Value 


PICTURE 


Edited Data 


9(5) 


12345 


$$$,$$9.99 


$12,345.00 


9(5) 


00123 


$$$,$$9.99 


$123.00 


9(5) 


00000 


$$$,$$9.99 


$0.00 


9(4) V 9 


12345 


$$$,$$9.99 


$1,234.50 


V9(5) 


12345 


$$$,$$9.99 


$0.12 


S9(5) 


00123 


99 


123.00 


S9(5) 


-00001 


,99 


-1.00 


S9(5) 


00123 


+++++++.99 


+123.00 


S9(5) 


00001 


— -.99 


1.00 


9(5) 


00123 


+++++++.99 


+123.00 


9(5) 


00123 


.99 


123.00 


S9(5) 


12345 


*******.99CR 


**12345.00 


S999V99 


02345 


zzzvzz 


2345 


3999 V 99 


00004 


zzzvzz 


04 


VALUE CLAUSE 









The VALUE clause specifies the initial value of working-storage items. The 
format of this clause is: 

VALUE IS literal 

The VALUE clause must not be written in a Data Description entry that also has 
an OCCURS or REDEFINES clause, or in an entry that is subordinate to an entry 
containing an OCCURS or REDERNES clause. Furthermore, it cannot be used in 
the File or Linkage Sections, except in level 88 condition descriptions. 
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The size of a literal given in a VALUE clause must be less than or equal to the 
size of the item as given in the PICTURE clause- The positioning of the literal 
within a data area is the same as would result from specifying a MOVE of the 
literal to the data area, except that editing characters in the PICTURE have no 
effect on the initialization, nor do BLANK \MHEN ZERO or JUSTIFIED clauses. 
The type of literal written in a VALUE clause depends on the type of data item, 
as specified in the data item formats earlier in this text. For edited items, 
values must be specified as non-numeric literals, and must be presented in edited 
form. A figurative constant may be given as the literal* 

When an initial value is not specified, no assumption should be made regarding 
the initial contents of an item in Working-Storage, 

The VALUE clause may be specified at the group level, in the form of a 
correctly sized non-numeric literal, or a figurative constant* In these cases the 
VALUE clause cannot be stated at the subordinate levels with the group. 
However, the value clause should not be written for a group containing items 
with descriptions including JUSTIRED, SYNCHRONIZED and USAGE (other than 
USAGE IS DISPLAY)- (A form used in level 88 items is explained in Section 3.16) 



3.7 REDEFINES CLAUSE 

The REDEFINES clause specifies that the same area is to contain different data 
items, or provides an alternative grouping or description of the same data. The 
format of the REDEFINES clause is: 

REDEFINES data-name-2 

When written, the REDEFINES clause should be the first clause following the 
data-name that defines the entry. The data description entry for data-name-2 
should not contain a REDEFINES clause, nor an OCCURS clause. 

When an area is redefined, ail descriptions, of the area remain in effect. Thus, if 
B and C are two separate items that share the same storage area due to 
redefinition, the procedure statements MOVE X TO 8 or MOVE Y TO C could be 
executed at any point in the program. In the first case, 8 would assume the 
value of X and take the form specified by the description of 8. In the second 
case, the same physical area would receive Y according to the description of C. 



CO8OL-a0 Reference Manual - Release 4 34 

Data Division 



For purposes of discussion of redefinition, data-name-1 is termed the subject, 
and data-nanne-2 is called the object. The levels of the subject and object are 
denoted by s and t, respectively. The following rules must be obeyed in order to 
establish a proper redefinition. 

1. s must equal t, but must not equal 88. 

2. The object must be contained in the same record (01 group level item), 
unless s=t=01. 

3* Prior to definition of the subject and subsequent to definition of the 
object there can be no level numbers that are numerically less than s. 

The length of data-name-1, multiplied by the number of occurrences of 
data-name-1, may not exceed the length of data-name-2, unless the level of 
data-name-1 is 01 (permitted only outside the File Section). Data-name-1 and 
entries subordinate to data-name-1 must not contain any value clauses, except in 
level 88. In the File Section, multiple level 01 entries subordinate to any given 
FD represent implicit redefinitions of the same area. 



3.8 OCCURS CLAUSE 

The OCCURS clause is used in defining related sets of repeated data, such as 
tables, lists and arrays. It specifies the number of times, up to a maximum of 
1023, that a data item with the same format is repeated. Data Description 
clauses associated with an item whose description includes an OCCURS clause 
apply to each repetition of the item being described. VJhen the OCCURS clause is 
used, the data name that is the defining name of the entry must be subscripted 
or indexed whenever it appears in the Procedure Division. If this data-name is 
the name of a group item, then all data-names belonging to the group must be 
subscripted or indexed whenever they are used. 

The OCCURS clause must not be used in any Data Description entry having a 
level number 01 or 77. The OCCURS clause has the following format: 

OCCURS integer TIMES [INDEXED BY index-name...] 

Since the OCCURS clause can only be used at subordinate levels within a data 
record, the maximum size of a table is limited by the rules for the size of a 
group item. See Section 3.1.1 on "Group Items". 
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Subscripting ; Subscripting provides the facility for referring to data items in a 
table or list that have not been assigned individual data-names. Subscripting is 
determined by the appearance of an OCCURS clause in a data description. If an 
item has an OCCURS clause or belongs to a group having an OCCURS clause, it 
must be subscripted or indexed whenever it is used. See the chapter on Table 
Handling for explanations on Indexing and Index Usage. (Exception: the 
table-name in a SEARCH statement must be referenced without subscripts.) 

A subscript is a positive nonzero integer whose value determines an element to 
which a reference is being made within a table or list. The subscript may be 
represented either by a literal or a data-name that has an integer value. Whether 
the subscript is represented by a literal or a data-name, the subscript is enclosed 
in parentheses and appears after the terminal space of the name of the element. 
A subscript must be a decimal or binary item. (The latter is strongly 
recommended, for the sake of efficiency.) 

At most three OCCURS clauses may govern any data item. Consequently, one, 
two or three subscripts may be required. When more than one subscript is 
required, they are written in the order of successively less inclusive dimensions 
of the data organization. Multiple subscripts are separated by commas, viz. 
ITEM (I, J). 

Example: 

01 ARRAY. 

03 ELEMENT, OCCURS 3, PICTURE 9(4). 

The above example would be allocated storage as shown below. 



ELEMENT (1) 



ELEMENT (2) 



ELEMENT (3) 



ARRAY, consisting of twelve 
characters; each item has 4 
digits. 



A data-name may not be subscripted if it is being used for: 
L a subscript 

2. the defining name of a data description entry 

3. data-name-2 in a REDEFINES clause 

4. a qualifier 
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3.9 SYNCHRONIZED CLAUSE 

The SYNCHRONIZED clause was designed In order to allocate space for data in 
an efficient manner, with respect to the computer central "memory." However, 
in this compiler, the SYNCHRONIZED specification is treated as commentary 
only. 

The format of this clause is: 

SYNC I SYNCHRONIZED [LEFT | RIGHT] 



3.10 BLANK WHEN ZERO CLAUSE 

The BLANK WHEN ZERO clause specifies that a report (edited) field is to 
contain nothing except blanks if the numeric value moved to it has a value of 
zero. When this clause is used with a numeric picture, the field is considered a 
report field. 



3.11 JUSTIFIED CLAUSE 

The JUSTIFIED RIGHT clause is only applicable to unedited alphanumeric 
(character string) items. It signifies that values are stored in a right-to-ieft 
fashion, resulting in space fill on the left when a short field is moved to a longer 
JUSTIRED field, or in truncation on the left when a long field is moved to a 
shorter JUSTIFIED field- The JUSTIFIED clause is effective only when the 
associated field is employed as the "receiving" field in a MOVE statement. 

The word JUST is a permissible abbreviation of JUSTIFIED. 



3.12 SIGN CLAUSE 

For an external decimal item, there are four possible manners of representing an 
operational sign; the choice is controlled by inclusion of a particular form of the 
SIGN clause, whose general form is: 

( trailing ) 

[SIGN IS] [ leading J [ SEPARATE CHARACTER] 

The following chart summarizes the effect of four possible forms of this clause. 



SIGN Clause 


Sign Representation 


TRAILING 
LEADING 

TRAILING SEPARATE 
LEADING SEPARATE 


Embedded in rightmost byte 
Embedded in leftmost byte 
Stored in separate rightmost byte 
Stored in separate leftmost byte 
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When the above forms are written, the PICTURE must begin with S, If no S 
appears, the item is not signed (and is capable of storing only absolute values), 
and the SIGN clause is prohibited. When S appears at the front of a PICTURE but 
no SIGN clause is included in an item's description, the "default" case SIGN IS 
TRAILING is assumed. 

The SIGN clause may be written at a group level; in this case the clause specifies 
the sign's format on any signed subordinate external decimal item. The 
SEPARATE CHARACTER phrase increases the size of the data item by 1 
character. The entries to which the SIGN clause apply must be implicitly or 
explicitly described as USAGE IS DISPLAY. 

(Note: When the CODE-SET clause is specified for a file, all signed numeric data 
for that file must be described with the SIGN IS SEPARATE clause.) 



3.13 LEVEL 88 CONDITION-NAMES 

The level 88 condition-name entry specifies a value, list of values, or a range of 
values that an elementary item may assume, in which case the named condition 
is true, otherwise false. The format of a level 88 item's value clause is 

VALUE IS literal-1 [Iiteral-2...] 

VALUES ARE literal-l THRU literal-Z 

A level 88 entry must be preceded either by another level 38 entry (in the case 
of several consecutive condition-names pertaining to an elementary item) or by 
an elementary item (which may be FILLER). Index data items should not be 
followed by level 88 items. 

Every condition-name pertains to an elementary item in such a way that the 
condition-name may be qualified by the name of the elementary item and the 
elementary item's qualifiers. A condition-name is used in the Procedure Division 
in place of a simple relational condition. A condition-name may pertain to an 
elementary item (a conditional variable) requiring subscripts. In this case, the 
condition-name, when written in the Procedure Division, must be subscripted 
according to the same requirements as the associated elementary item. The 
type of literal in a condition-name entry must be consistent with the data type 
of the conditional variable. In the following example, PAYROLL-PERIOD is the 
conditional variable- The picture associated with it limits the value of the 88 
condition-name to one digit. 

02 PAYROLL-PERIOD PICTURE IS 9. 
88 WEEKLY VALUE IS 1. 
88 SEMI-MONTHLY VALUE IS 2. 
88 MONTHLY VALUE IS 3. 
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Using the above description, the following procedural condition-name test may 
be written: 

IF MONTHLY GO TO DO-MONTHLY 

An equivalent statement is: 

IF PAYROLL -PERIOD = 3 GO TO DO-MONTHLY. 

For an edited elementary item, values in a condition-name entry must be 
expressed in the form of non-numeric literals. 

A VALUE clause may not contain both a series of literals and a range of literals. 



3.14 FILE SECTION , FD ENTRIES (SEQUENTIAL I-O ONLY) 

In the FILE SECTION of the Data Division, an FD entry (file description) must 
appear for every SELECTed file. This entry precedes the descriptions of the 
filers record structure(s). 

The general format of an FD entry is: 

FD file name LABEL-clause [ VALUE -OF-clause] 
[DATA-RECORD(S)-clause] [BLOCK-ciause] [RECORD-clause] 
[CODE-SET-clause] [LINAGE clause]. 

After "FD filename," the order of the clauses is immaterial. 

3.14.1 LABEL CLAUSE 

The format of this required FD entry clause is: 

( record \ flS 1 ( OMITTED \ 
LABEL \ RECORDS ) LaREJ (STANDARD) 

The OMITTED option specifies that no labels exist for the file; this must be 
specified for files assigned to PRINTER. 

The STANDARD option specifies that labels exist for the file and that the labels 
conform to system specifications; this must be specified for files assigned to 
DISK. 
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3.14.2 VALUE OF CLAUSE 

The VALUE OF clause appears in any FD entry for a DISK-assigned file, and 
contains a filename expressed as a non-numeric literal of at most 16 characters 
or as a data-name. The filename is specified according to the rules for 
filenames of the operating system being used. It must not contain any embedded 
space characters. If a data-name is specified, the filename it contains may be as 
many characters as desired, but it must be terminated by a space character. The 
general form is: 



I data-name] 
\ 
literal j 

Examples: 

V ALUE OF FILE-ID "A:MASTER.ASM" (CP/M) 

VALUE OF FILE-ID "EMPL0Y/DAT:2" (TRSDOS Model II) 

V ALUE OF FILE-ID ":F1:IN V NT.LST" (ISIS-D) 

A reminder: if a file is ASSIGNed to PRINTER, it is unlabeled and the VALUE 
clause must not be included in the associated FD. If a file is ASSIGNed to DISK, 
it is necessary to include both LABEL RECORDS STANDARD and VALUE 
clauses in the associated FD. See the COBOL-80 User's Guide for filename 
formats for specific operating systems. 



3.14.3 DATA RECORD(S) CLAUSE 

The optional DATA RECORDS clause identifies the records in the file by name. 
This clause is documentary only, in this and all COBOL systems. Its general 
format is: 



DATA 



RECORD IS \ 



RECORDS ARE 



• data-name-1 Cdata-name-2...] 



The presence of more than one data-name indicates that the file contains more 
than one type of data record. That is, two or more record descriptions may 
apply to the same storage area. The order in which the data-names are listed is 
not significant. 

Data-name-1 , data-name-2 , etc., are the names of data records, and each must 
be preceded in its record description entry by the level number 01, following the 
appropriate file description (FD) in the File Section. 
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3,14.4 BLOCK CLAUSE 

The BLOCK CONTAINS clause is used to specify characteristics of physical 
records in relation to the concept of logical records. The general fornnat is: 



BLOCK CONTAINS integer-2 



characters' 

RECORDS 



Files assigned to PRINTER must not have a BLOCK clause in the associated FD 
entry* Furthernnore, the BLOCK clause has no effect on disk files in this COBOL 
system, but it is examined for correct syntax. It is normally applicable to tape 
files, which are not supported by this COBOL. 

When used, the size of a physical block is usually stated in RECORDS, except 
when the records are variable in size or exceed the size of a physical block; in 
these cases the size should be expressed in CHARACTERS. 

When the BLOCK CONTAINS clause is omitted, it is assumed that records are 
not blocked. When neither the CHARACTERS nor the RECORDS option is 
specified, the CHARACTERS option is assumed. When the RECORDS option is 
used, the compiler assumes that the block size provides for inteqer«2 records of 
maximum size and then provides additional space for any required control 
characters. 



3.14.5 RECORD CLAUSE 

Since the size of each data record is defined fully by the set of data description 
entries constituting the record (level 01) declaration, this clause Is always 
optional and documentary. The format of this clause is: 

RECORD CONTAINS [integer-l TO] integer-Z CHARACTERS 

Integer-2 should be the size of the biggest record in the file declaration. If the 
records are variable in size, integer-1 must be specified and must equal the size 
of the smallest record. The sizes are given as character positions required to 
store the logical records. 
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3,14,6 CODE-SET CLAUSE 

The format of this clause is: 

CODE-SET IS ASCII 

The CODE-SET clause, which should be specified only for non-mass-storage files, 
serves only the purposes of documentation in this compiler, reflecting the fact 
that both internal and external data are represented in ASCII code. However, 
any signed numeric data description entries in the file's records should include 
the SIGN IS SEPARATE clause and all data in the file should have USAGE 
DISPLAY. 



3.14,7 LINAGE CLAUSE 

For a file assigned to PRINTER, the LINAGE clause provides a means of 
specifying the size of the printable portion of a page, called the "page body." The 
number of lines in the page body is specified along with, optionally, the size of 
the top and bottom margins and the line number within the page body at which a 
footing area begins- The general format is: 



Idata-name-1] [data-name-Z ] 

> LINES, [WITH FOOTING AT j [ ] 

integer-1 j (integer-2 j 



(data-name-3] rdata-name-4^ 

[ ] [LINES AT BOTTOM I \ 

integer-3 j I integer -4 j 

All data-names must refer to unsigned numeric integer data items. Integer-1 
must be greater than zero, and integer-2 must not be greater than integer-1. 

The total page size is the sum of the values in each phrase except for FOOTING. 
If TOP or BOTTOM margins are not specified, their size is assumed zero. The 
footing area comprises that part of the page body betv/een the line indicated by 
the FOOTING value, and the last line of the page body, inclusive. 

The values in each phrase at the time the file is opened (by the execution of an 
OPEN OUTPUT statement) specify the number of lines that comprise each of the 
sections of the first logical page. Whenever a WRITE statement with the 
ADVANCING PAGE phrase is executed or a "page overflow" condition occurs 
(see the WRITE statement), the values in each phrase, at that time, will be used 
to specify the number of lines in each section of the next logical page. 
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A LINAGE-COUNTER is created by the presence of a LINAGE clause. The value 
in the LINAGE-COUNTER at any given time represents the line number at which 
the printer is positioned within the current page body. LINAGE-COUNTER may 
be referenced but may not be modified by Procedure Division statements* It is 
automatically modified during execution of a WRITE statement, according to the 
following rules: 

1. When the "ADVANCING PAGE" phrase of the WRITE statement is specified 
or a "page overflow" condition occurs (see the WRITE statement), the 
LINAGE COUNTER is reset to one. 

2. When the "ADVANCING identifier or integer" phrase is specified, 
LINAGE-COUNTER is incremented by the ADVANCING value. 

3. When the ADVANCING phrase is not specified, LINAGE-COUNTER is 
incremented by one. 

See the description of the WRITE statement for additional information about the 
effects of LINAGE specifications. 



5-15 WORKING-STORAGE SECTION 

The second section of the DATA DIVISION begins with the following header: 

WORKING-STORAGE SECTION . 

This section describes records and other data which are not part of external data 
files but which are developed and processed internally. 

Data description entries in this section may employ level numbers 01-49, as in 
the File Section, as well as 77. Value clauses, prohibited in the File Section 
(except for level 88), are permitted throughout the Working-Storage Section. 



3.16 LINKAGE SECTION 

The third section of the Data Division is defined by the header: 

LINKAGE SECTION, 

In this section, the user describes data by name and attribute, but storage space 
is not allocated. Instead, these "dummy" descriptions are applied (through the 
mechanism of the USING list on the Procedure Division header) to data whose 
addresses are passed into a subprogram by a call upon it from a separately 
compiled program. Consequently, VALUE clauses are prohibited in the Linkage 
Section, except in level 88 condition-name entries. Refer to Chapter 5, 
Inter-Program Communication, for further information; 
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3.17 SCREEN SECTION 

The fourth section of the Data Division is used to define CRT screen formats and 
is composed of screen data description entries. As in the File and 
Working-Storage sections, descriptions may be grouped through the assignment of 
appropriate level numbers. Thus there are two types of screen items. 
Elementary screen items define the individual display and/or data entry fields 
within the screen layout. Group screen items are used to name any group of 
elementary screen items so that they may be ACCEPTed or DISPLAYed with a 
single Procedure Division statement. The format of a group screen description 
entry is: 

level-number screen-name [A UTO ] [SECURE ]. 

level number must be an integer in the range 01 through 49. screen-name must 
conform to the rules for the formation of names given in section 1.3. The group 
screen description entry must be followed by one or more subordinate screen 
items as indicated by increasing level-numbers. If AUTO or SECURE is coded for 
a group screen item, the effect is as if AUTO or SECURE had been coded for 
every elementary screen item subordinate to that group screen item. 

The format of an elementary screen item is: 

ievel-number [screen-name] 
[BLANK SCREEN ] 
[line NUMBER is [ PLUS ] integer-1] 
[COLUMN NUMSERIsT PLUS ] integer-2] 
[BLANK LINE] 

[Han 



Q HIGHLIGHT ) 1 
BLINK jj 



[VALUE ] IS literal-1 

^ [FROM 1 llJe^^^^^^^^^ 3 [TO identifier-2] 

[USING identifier-3] 



( PICTURE ) 

i piQ 1 IS picture-String 



[BLANK WHEN ZE R O] 
[ 



JUSTinED I 

JUST ) RIGHT] 

[AUTO] 
[SECDRE] 
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level-number and screen-name are subject to the same rules as in the group screen data 
description. The order of clauses in the elementary screen data description entry is not 
significant, except that screen-name, if present, must immediately follow level-number. 
If PICTURE is coded, then either USIMG or at least one of FROM and TO must be 
present* A screen item may have both a FROM and TO clause, AUTO, SECURE, BLANK 
WHEN ZERO, and JUSTIFIED may be given only if PICTURE is specified. The maximum 
length of an elementary screen item is 80 characters. 

The clauses specified with each elementary screen data description can affect data input 
and data display operations when ACCEPT and DISPLAY statements are executed at 
runtime. The effects of each specification are as follows: 

1. BLANK SCREEN causes the entire screen to be erased and the cursor to be 
placed at the home position (line 1, column 1). 

2. LINE and COLUMN affect the screen location associated with an elementary 
screen item. As the SCREEN SECTION is processed at compile time, a 
current cursor position is maintained so that each elementary screen item 
can be identified with a particular region of the screen. When a level 01 
screen item is encountered, the current screen position is reset to line 1, 
column 1. Then, as each elementary screen data description is processed, the 
current position is adjusted for the size of each definition. Therefore, by 
default, successively defined fields appear end to end in successive areas of 
the CRT screen. The position current at the start of any elementary screen 
data description may be changed by means of the LINE and COLUMN 
specifications- If neither LINE nor COLUMN is coded, the current screen 
position is not changed. If COLUMN is coded without LINE, the current 
screen line is not adjusted. If LiNE is coded without COLUMN, COLUMN 1 is 
assumed. The LINE integer or COLUMN integer clause without PLUS causes 
the specified integer to be taken as the line or column at which the current 
screen item should start. The LINE PLUS integer or COLUMN PLUS integer 
clause causes the specified integer to be added to the current screen line or 
column, and the result to be used as the line or column at which the current 
screen item should start. If LINE (COLUMN) is given without integer-l 
(integer-2), LINE PLUS 1 (COLUMN PLUS 1) is assumed. 

3. BLANK LINE causes erasure of the screen from the current cursor position to 
the end of the current line and leaves the cursor position unchanged. 



NOTE 

The following functions are always executed in 
the order shown below, regardless of the order 
in which they are specified. 



1. BLANK SCREEN 

2. LINE/COLUMN positioning 

3. BLANK LINE 

4. Display or accept operation 
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4. BELL will sound the terminal's audio alarm, if the terminal is so 
equipped, when the system is ready to ACCEPT the field. BELL has 
no effect on output fields, 

5. HIGHLIGHT and BLINK are synonymous. They cause a DISPLAY 
screen item to appear on the CRT highlighted by flashing, high 
intensity, inverted video, or some other method provided by the 
particular type of terminal hardware in use. HIGHLfGHT has no 
effect on input fields. 

6. VALUE IS literal-1 explicitly specifies the character string which 
should be displayed on the screen when the screen item being 
defined is referenced by a DISPLAY statement, literal-1 must be 
bounded by quotes and cannot be a figurative constant. A screen 
item for which VALUE is specified is ignored by all ACCEPT 
statements. 

7. PICTURE specifies the format in which data is to be presented on 
the screen. It is coded according to the rules for Working-Storage 
PICTURE clauses described in section 3.2. During a DISPLAY 
statement, the contents of a FROM or USING field are MOV Ed to 
an implicit temporary item with the specified PICTURE before 
being displayed on the screen. During an ACCEPT statement, the 
displayed contents of the field being entered are punctuated so as to 
conform with the given PICTURE format. 

8. FROM, TO, and USING describe relationsips between a screen item 
and literals and/or fields in the File, Working-Storage, and/or 
Linkage sections. On DISPLAY of a screen item, a MOVE occurs 
from any FROM or USING literal or field to a temporary item 
defined by the screen item's PICTURE. The resulting contents of 
the temporary item are then exhibited on the screen. On an 
ACCEPT of the screen item, the runtime system implicitly MOVEs 
the ACCEPTed data to any TO or USING field specified for the item. 

9. BLANK WHEN ZERO causes a screen item to be displayed as spaces 
if its value is zero. 

10. JUSTIFIED and JUST specify that operator-keyed data or data from 
a FROM field, USING field, or literal is aligned with the right 
boundary of the screen item when it is displayed on the screen. 

11. AUTO specifies that when a field has been filled by operator input, 
the cursor automatically skips to the next input field, rather than 
waiting for a terminator character to be typed. If there are no 
more input fields remaining, the ACCEPT is terminated. 

12. SECURE suppresses the echoing of input characters. Instead, an 
asterisk is displayed for each data character ACCEPTed. 
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3.18 DATA DIVISION LIMITATIONS 

There is a llnnitation on the number of itenns in the Working-Storage, Linkage, 
and File sections of the Data Division. In those implementations of COBOL-80 
which have the Communications Level I facility, the number of CDs is relevant 
aiso« The sum: 

W+4095 

+F+L+C 

4096 

must be less than or equal to 14, where W is the size of Working-Storage in bytes, 
F is the number of files described in the File Section, L is the number of level 01 
or 77 entries in the Linkage Section, and C is the number of CD's in the 
Communications Section. Furthermore, the maximum number of files which may 
be open in the same run unit (main program linked together with an arbitrary 
number of subprograms) is 14, 
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In this chapter, the basic concepts of the Procedure Division are explained. 
Advanced topics (such as indexing of tables, indexed file accessing, interprogram 
communication and declaratives) are discussed in subsequent chapters. 



4.1 STATEMENTS, SENTENCES. PROCEDURE-NAMES 

The Procedure portion of a source program specifies those procedures needed to 
peform a particular data processing function. These steps (computations, logical 
decisions, etc.) are expressed in statements similar to English, which employ the 
concept of verbs to denote actions, and statements and sentences to describe 
procedures. The Procedure portion must begin with the following header: 

PROCEDURE DIVISION. 



A statement consists of a verb followed by appropriate operands (data-names or 
literals) and other words that are necessary for the completion of the 
statement. The two types of statements are imperative and conditional. 

Imperative Statements 

An imperative statement specifies an unconditional action to be taken by 
the object program. An imperative statement consists of a verb and its 
operands, excluding the IF and SEARCH conditional statements and any 
statement which contains an INVALID KEY, AT END, SIZE ERROR, 
OVERFLOW, or ON ESCAPE clause. 

Conditional Statements 

A conditional statement stipulates a condition that is tested to determine 
whether an alternate path of program flow is to be taken. The IF and 
SEARCH statements provide this capability. Any I/O statement having an 
INVALID KEY or AT END clause is also considered to be conditional. 
When an arithmetic statement posesses a SIZE ERROR suffix, the 
statement is considered to be conditional rather than imperative. STRING 
or UNSTRING statements having an OVERFLOW clause and ACCEPT with 
the ON ESCAPE clause are also conditional. 
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Sentences 

A sentence is a single statement or a series of statements terminated by a 
period and followed by a space. If desired, a semi-colon or comma may be 
used between statements in a sentence* 

Paragraphs 

A paragraph is a logical entity consisting of zero, one or more sentences. 
Each paragraph must begin with a paragraph-name* 



Sections 

A section is composed of one or more successive paragraphs, and must 
begin with a section-header. A section header consists of a section-name 
conforming to the rules for procedure-name formation, followed by the 
word SECTION, an optional segment number, and a period. A section 
header must appear on a line by itself. Each section-name must be unique. 



4.2 ORGANIZATION OF THE PROCEDURE DIVISION 

The procedure part of a program may be subdivided in three possible ways: 

1. The Procedure Division consists only of paragraphs. 

2 The Procedure Division consists of zero or more paragraphs followed 
by a number of sections (each section subdivided into one or more 
paragraphs). 

3. The Procedure Division consists of a DECLARATIVES portion and a 
series of sections (each section subdivided into one or more 
paragraphs). 

The DECLARATIVES portion of the Procedure Division is optional; it provides a 
means of designating a procedure to be Invoked in the event of an I/O error. If 
Declaratives are utilized, only possibility 3 may be used. Refer to Chapter 9 for 
a complete discussion. 
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4.3 MOVE STATEMENT 

The MOVE statement is used to move data from one area of main storage to 
another and to perform conversions and/or editing on the data that is moved. 
The MOVE statement has the following format: 

MOVE (data-name-l) TO data-name-2 Cdata-name-3.-] 
[literal j 

The data represented by data-name-1 or the specified literal is moved to the 
area designated by data-name-2. Additional receiving fields may be specified 
(data-name-3 etc.). Mrtnen a group item is a receiving fieid^ characters are moved 
without regard to the level structure of the group involved and without editing. 

Subscripting or indexing associated with data-name-2 is evaluated immediately 
before data is moved to the receiving field. The same is true for other receiving 
fields (data-name-3, etc., if any). But for the source field, subscripting or 
indexing (associated with data-name-1) is evaluated only once, before any data is 
moved. 

To illustrate, consider the statement 

MOVE ACS) TO 8, C (B), 

which is equivalent to 

MOVE A (B) TO temp 
MOVE temp TO 8 
MOVE temp TO C (B) 

where temp is an intermediate result field assigned automatically by the 
compiler. 

The following considerations pertain to moving items: 

1. Numeric (external or internal decimal, binary, numeric literal, or 
ZERO) or alphanumeric to numeric or report: 

a. The items are aligned by decimal points, with generation of 

zeros or truncation on either end, as required. If source is 
alphanumeric, it is treated as an unsigned integer and should 
not be longer than 31 characters. 



b. When the types of the source field and receiving field differ, 

conversion to the type of the receiving field takes place. 
Alphanumeric source items are treated as unsigned integers 
with Usage Display. 
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c* The items may have special editing performed on them with 

suppression of zeros, insertion of a dollar sign, etc., and 
decimal point alignment, as specified by the receiving area, 

d. One should not move an item whose PICTURE declares it to be 

alphabetic or alphanumeric edited to a numeric or report item, 
nor is it possible to move a numeric item of any sort to an 
alphabetic item though numeric integers and numeric report 
items can be moved to alphanumeric items with or without 
editing, but operational signs are not moved in this case even 
if "SIGN IS SEPARATE" has been specified. 

Non-numeric sourceand destinations: 



a. The characters are placed in the receiving area from left to 
right, unless JUSTIFIED RIGHT applies. 

b. If the receiving field is not completely filled by the data being 
moved, the remaining positions are filled with spaces. 

c. If the source field is longer than the receiving field, the move 
is terminated as soon as the receiving field is filled. 

3. When overlapping fields are involved, results are not predictable. 

4. Appendix II shows, in tabular form, all permissible combinations of 
source and receiving field types. 

5. An item having USAGE IS INDEX cannot appear as an operand of a 
MOVE statement. See SET in Chapter 6, Table Handling. 

Examples of Data Movement (b represents blank): 



Source Field 


Receiving Field 


PICTURE 


Value 


PICTURE 


Value before MOVE 


Value after MOVE 


99V99 
99 V 99 
S9V9 
XXX 
9V99 


1234 

1234 

12- 

A2B 

123 


S99V99 
99V9 
99 V 999 
XXXXX 

99.99 


9876- 

987 

98765 

Y9X8W 

87,65 


1234+ 

123 

01200+ 

A2Bbb 

01.23 
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4,4 INSPECT STATEMENT 

The INSPECT statement enables the programmer to examine a character-string 
item. Options permit various combinations of the following actions: 

1. counting appearances of a specified character 

2* replacing a specified character with another 

3, limiting the above actions by requiring the appearance of other 
specific characters 

The format of the INSPECT statement is: 

INPECT data-name-1 [TALLYING-clause] [REPLACING-clause] 

where TALLYING-ciause has the format 

I CHARACTERS 
TALLYING data-name-2 FOR \ ALL | LEADING operand-3 

[ BEFORE I AFTER INITIAL operand-4] 

and REPLACING-ciause has the format 

[ characters ] 

REPLACING [ALL I LEADING I FIRST operand-sj BY operand-6 

[ BEFORE I AFTER INITIAL operand-7] 

Because data-name-1 is to be treated as a string of characters by INSPECT, it 
must not be described by USAGE IS INDEX, COMP, or COMP-3. Data-name-2 
must be a numeric data'item. 

In the above formats, operand-n may be a quoted literal of length one, a 
figurative constant signifying a single character, or a data-name of an item 
whose length is one, 

TALLYING-ciause and REPLACING-ciause may not both be omitted; if both are 
present, TALLYING-ciause must be first. 
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TALLYING-clause causes character-fay-character comparison, from left to right, 
of data-name-1, incrementing data-name-2 by one each time a match is found. 
When an AFTER INITIAL operand-4 subclause is present, the counting process 
begins only after detection of a character in data-name-1 matching operand-4. 
If BEFORE INITIAL operand-4 is specified, the counting process terminates upon 
encountering a character in data-name-1 which matches operand-4. Also going 
from left to right, REPLACING-clause causes replacement of characters under 
conditions specified by the REPLACING-clause. If BEFORE INITIAL operand-7 
is present, replacement does not continue after detection of a character in 
data-name-1 matching operand-7. If AFTER INITIAL operand-7 is present, 
replacement does not commence until detection of a character in data-name-1 
matching operand-7. 

With bounds on data-name-1 thus determined, TALLYING and REPLACING is 
done on characters as specified by the following: 

1. "CHARACTERS" implies that every character in the bounded 
data-name-1 is to be TALLYed or REPLACEd. 

2. "All operand" means that all characters in the bounded data-name-1 
which match the "operand" character are to participate in 
TALLYing/REPLACing. 

3. "LEADING operand" specifies that only characters matching 
"operand" from the leftmost portion of the bounded data-name-1 
which are contiguous (such as leading zeros) are to participate in 
TALLYIng or REPLACing. 

4. "RRST operand" specifies that only the first-encountered character 
matching "operand" is to participate in REPLACing. (This option is 
unavailable in TALLYing.) 

When both TALLYING and REPLACING clauses are present, the two clauses 
behave as if two INSPECT statements were written, the first containing only a 
TALLYING-clause and the second containing only a REPLACING-clause. 

In developing a TALLYING value, the final result in data-name-2 is equal to the 
tallied count plus the initial value of data-name-2. In the first example below, 
the item COUNTX is assumed to have been set to zero initially elsewhere in the 
program. 
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INSPECT ITEM TALLYING COUNTX FOR ALL "L" REPLACING LEADING "A" 
BY "E" AFTER INITIAL "L" 



Original (ITEM): 


SALAMI 


ALABAMA 


Result (ITEM): 


SALEMI 


ALEBAMA 


Final (COUNTX): 


1 


1 



INSPECT WORK -AREA REPLACING ALL DELIMITER BY TRANSFORMATION 



Original (WORK-AREA): NEW YORK N Y 

Original (DELIMITER): (space) 

Original (TRANSFORMATION): . (period) 

Result (WORK-AREA): NEW.YORK..N.Y. 



(length 16) 



NOTE 

If any -data-name-1 or operand-n is 
described as signed numeric, it is treated 
as if it were unsigned. 



4.5 ARITHMETIC STATEMENTS 

There are five arithnnetic statements: ADD, SUBTRACT, MULTIPLY, DIVIDE 
and COMPUTE. Any arithmetic statement may be either imperative or 
conditional. When an arithmetic statement includes an ON SIZE ERROR 
specification, the entire statement is termed conditional, because the size error 
condition is data-dependent. 

An example of a conditional arithmetic statement is: 

ADD 1 TO RECORD-COUNT 

ON SIZE ERROR MOVE ZERO TO RECORD-COUNT 
DISPLAY ''LIMIT 99 EXCEEDED". 

If a size error occurs (in this case, it is apparent that RECORD-COUNT has 
PICTURE 99, and cannot hold a value of 100), both the MOVE and DISPLAY 
statements are executed. 



The three statement components that may appear in arithmetic statements 
(GIVING option, ROUNDED option, and SIZE ERROR option) are discussed in 
detail later in this section. 
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Basic Rules for Arithmetic Statements 

1. Ail data-names used in arithmetic statements must be elementary 
numeric data items that are defined in the Data Division of the 
program, except that operands of the GIVING option may be report 
(numeric edited) items. Index-names and index data items are not 
permissible in these arithmetic statements (see Chapter 6). 

2. Decimal point alignment is supplied automatically throughout the 
computations, 

3. Intermediate result fields generated for the evaluation of arithmetic 
expressions assure the accuracy of the result field, except where 
high-order truncation is necessary. 

4,5.1 SIZE ERROR OPTION 

If, after decimal-point alignment and any low-order rounding, the absolute value 
of a calculated result exceeds the largest value which the receiving field is 
capable of holding, a space size error condition exists. 

The optional SIZE ERROR clause is written immediately after any arithmetic 
statement, as an extension of the statement. The format of the SIZE ERROR 
option is: 

ON SIZE ERROR imperative statement ... 

If the SIZE ERROR option is present, and a size error condition arises, the value 
of the resultant data-name is unaltered and the series of imperative statements 
specified for the condition is executed. 

If the SIZE ERROR option has not been specified and a size error condition 
arises, no assumption should be made about the final result. 

An arithmetic statement, if written with the SIZE ERROR option, is not an 
imperative statement. Rather, it is a conditional statement and is prohibited in 
contexts where only imperative statements are allowed. 
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4.5.2 ROUNDED OPTION 

If, after decimal-point alignment, the number of places in the fraction of the 
result is greater than the number of places in the fractional part of the data 
item that is to be set equal to the calculated result, truncation occurs unless the 
ROUNDED option has been specified. 

When the ROUNDED option is specified, the least significant digit of the 
resultant data-name has its value increased by 1 whenever the most significant 
digit of the excess is greater than or equal to 5. 

Rounding of a computed negative result is performed by rounding the absolute 
value of the computed result and then making the final result negative. 

The following chart illustrates the relationship between a calculated result and 
the value stored in an item that is to receive the calculated result, with and 
without rounding. 





Item to Receive Calculated Result 


Calculated 
Result 


PICTURE 


Value After 
Rounding 


Value After 
Truncating 


-12.36 

8.432 

35.6 

65.6 

.0055 


S99V9 

9V9 

99V9 

S99V 

SV999 


-12.4 

8.4 

35.6 

.006 


-12.3 

8.4 

35.6 

65 

.005 



Illustration of Rounding 

When the low order integer positions in a resultant-Identifier are represented by 
the character P in its PICTURE, rounding or truncation occurs relative to the 
rightmost integer position for which storage is allowed. 



4.5.3 GIVING OPTION 

If the GIVING option is written, the value of the data-name that follows the 
word GIVING is made equal to the calculated result of the arithmetic operation. 
The data-name that follows GIVING is not used in the computation and may be a 
report (numeric-edited) item. 
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4,5.4 ADD STATEMENT 

The ADD statement adds two or more numeric values and stores the resulting 
sum. The ADD statement general format is: 



fnumeric-llteral) 
ADD I data-name-1 ) 



(IS I 

I GIVING ! 



VlNGjdata-name-n [ ROUNDED ] [SIZE-ERROR-ciause] 

When the TO option is used, the values of ail the data-names (including 
data-name-n) and literals in the statements are added, and the resulting sum 
replaces the value of data-name-n. \Vhen the GIVING option is used, at least two 
data-names and/or numeric literals must be coded between ADD and GIVING. 
The sum of the values of these data-names and literals (not including 
data-name-n) replaces the value of data-name-n. 

The following are examples of proper ADD statements: 

ADD INTEREST, DEPOSIT TO BALANCE ROUNDED 
ADD REGULAR-TIME OVERTIME GIVING GROSS-PAY. 

The first statement would result in the sum of INTEREST, DEPOSIT, and 
BALANCE being piaced at BALANCE, while the second would result in the sum 
of REGULAR-TIME and OVERTIME earnings being piaced in item GROSS-PAY. 



4.5.5 SUBTRACT STATEMENT 

The SUBTRACT statement subtracts one or more numeric data items from a 
specified item and stores the difference. 



The SUBTRACT statement general format is 

l-l) ..• 



fdata-name-l 
SUBTRACT numeric-literal-lj ..• FROM 



jdata-name-m [ GIVING data-name-n] 
[numeric literal-m GIVING data-name-n 

[ ROUNDED ] [SIZE-ERROR -clause] 

The effect of the SUBTRACT statement is to sum the values of ail the operands 
that precede FROM and subtract that sum from the value of the item following 
FROM. 

The result (difference) is stored in data-name-n, if there is a GIVING option. 
Otherwise, the result is stored in data-name-m. 
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4,5,6 MULTIPLY STATEMENT 

The MULTIPLY statement multiplies two numeric data items and stores the 
product. 

The general format of the MULTIPLY statement is: 

MULTIPLY jdata-name-1 

(numeric-literal-l 

BY (data-name-Z [ GIVING data-name-3] | 
inumeric-literal-2 GIVING data-name-3| 

[ ROUNDED ] [SIZE-ERRGR-ciause] 

VVhen the GIVING option is omitted, the second operand must be a data-name; 
the product replaces the value of data-name-2. For example, a new BALANCE 
value is computed by the statement MULTIPLY 1.03 BY BALANCE. (Since this 
order may seem somewhat unnatural, it is recommended that GIVING always be 
written, e.g. MULTIPLY 1.03 BY BALANCE GIVING BALANCE.) 



4.5.7 DIVIDE STATEMENT 

The DIVIDE statement divides two numeric values and stores the quotient. The 
general format of the DIVIDE statement is: 

DIVIDE fdata-name-1 1 jBX | fdata-name-2 

I numeric-literal-l I ( INTO ) lnumeric-iiteral-2 

[ GIVING data-name-33 [ ROUNDED ] [SIZE-ERROR-clause] 

The BY-form signifies that the first operand (data-name-1 or numeric-literal-l) 
is the dividend (numerator), and the second operand (data-name-2 or 
numeric-literal-2) is the divisor (denominator). If GIVING is not written in this 
case, then the first operand must be a data-name, in which the quotient is stored. 

The INTO-form signifies that the first operand is the divisor and the second 
operand is the dividend. If GIVING is not written in this case, then the second 
operand must be a data-name, in which the quotient is stored. 

Division by zero always causes a size-error condition. 
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4.5.8 COMPUTE STATEMENT 

The COMPUTE statement evaluates an arithnnetic expression and then stores the 
result in a designated nunneric or report (numeric edited) item. 

The general format of the COMPUTE statement is: 

COMPUTE data-name-1 [ROUNDED ]•..=: 

(data-name-2 \ 

numeric-literal \ [SIZE-ERROR-clause] 

arithmetic-expression) 

An example of such a statement is: 

COMPUTE GROSS-PAY ROUNDED =: BASE-SALARY * 

(1 + 1.5 * (HOURS - 40) / 40). 

An arithmetic expression is a proper combination of numeric literals, 
data-names, arithmetic operators and parentheses. In general, the data-names in 
an arithmetic expression must designate numeric data. Consecutive data-names 
(or literals) must be separated by an arithmetic operator, and there must be one 
or more blanks on either side of the operator. The operators are: 

+ for addition 

for subtraction 
* for multiplication 
/ for division 

** for exponentiation to an integral power. 

When more than one operation is to be executed using a given variable or term, 
the order of precedence is: 

1. Unary (involving one variable) plus and minus 

2. Exponentiation 

3. Multiplication and Division 

4. Addition and Subtraction 

Parentheses may be used when the normal order of operations is not desired. 
Expressions within parentheses are evaluated first; parentheses may be nested to 
any level. Consider the following expression. 

A + B / (C - D * E) 
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Evaluation of the above expression is performed in the following ordered 
sequence: 

1. Compute the product D times E, considered as intermediate result Rl. 

2. Compute intermediate result R2 as the difference C - Rl. 
3« Divide B by R2, providing intermediate result R3. 

4. The final result is computed by addition of A to R3. 
Without parentheses, the expression 

A + B /C -D *E 

is evaluated as: 

Rl = B / C 

R2 = A ^- Rl 

R3 = D * E 

final result = R2 - R3 

VVhen parentheses are employed, the following punctuation rules should be used: 

1. A left parenthesis is preceded by one or more spaces- 

2. A ri^t parenthesis is followed by one or more spaces. 

The expression A - B - C is evaluated as (A - B) - C. Unary operators are 
permitted, e.g.: 

COMPUTE A = +C + -4.6 
COMPUTE X = -Y 
COMPUTE A, B(I) = •C - D(3) 

4.6 GO TO STATEMENT 

The GO TO statement transfers control from one portion of a program to 
another. It has the following general format: 

GO TO [procedure-name-l [ [procedure-name-2] ^.. DEPENDING ON data-name] ] 

The simple form GO TO procedure-name-l changes the path of control to a 
designated paragraph or section. If the GO statement is without a 
procedure-name, then that GO statement must be the only one in a paragraph, 
and must be ALTERed (see 4.12) prior to its execution. 
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The more general form designates N procedure-names as a choice of N paths to 
transfer to, if the value of data-name is 1 to N, respectively. Otherwise, there 
is no transfer of control and execution proceeds in the normal sequence. 
Data-name must be a numeric elementary item and have no positions to the right 
of the decimal point. 

If a GO (non-DEPENDING) statement appears in a sequence of imperative 
statements, it must be the last statement in that sequence. 



4,7 STOP STATEMENT 

The STOP statement is used to terminate or delay execution of the object 
program. 

The format of this statement is: 

( run ] 

STOP [literalj 

STOP RUN terminates execution of a program, closing all files and returning 
control to the operating system. If used in a sequence of imperative statements, 
it must be the last statement in that sequence. 

The form STOP literal displays the specified literal on the console and suspends 
execution. Execution of the program is resumed only after operator 
intervention. Presumably, the operator performs a function suggested by the 
content of the literal, prior to resuming program execution by pressing the 
carriage return key. 



4.3 ACCEPT STATEMENT 

The ACCEPT statement Is used by a processing program to obtain low-volume 
input at runtime. Four formats are available: 



Format 1: 



(\ 



DATE 

ACCEPT identifier-1 FROM DAY I 

< TIME > 

LINE NUMBER I 

I ESCAPE KEY I 



Format 2: 



ACCEPT identifier-2 
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Format 3: 



ACCEPT position-spec identifier-3 [ WITH 



/' SPACE-FILL 
ZERO-FILL 
LEFT-JUSTIFY 
RIGHT-JUSTIFY 
TRAILING-5IGN 
PROMPT 
UPDATE 
LENGTH-CHECK 
AUTO-SKIP 
BEEP 



..] 



Format 4; 

ACCEPT screen-name [ON ESCAPE imperative-statement] 

The function of each form of the ACCEPT statement is to acquire data from a 
source external to the program and place it in a specified receiving field or set 
of receiving fields. The forms differ primarily in the data source with which 
they are designed to interface. The format 1 ACCEPT obtains information from 
system-defined data items. The other formats of the ACCEPT statement 
receive data keyed in by an operator at the system console device. For format 
2, this device is assumed to be a teletype, a glass teletype, or a CRT terminal in 
scrolling mode. For format 3, it is assumed that the input device is a video 
terminal and that scrolling is not desired. The format 4 ACCEPT receives an 
entire data entry form (as defined in the SCREEN SECTION) when it has been 
completed by the terminal operator. Note that an ordinary CRT terminal is 
suitable as an input device for a format 2, 3, or 4 ACCEPT, although the possible 
effects on the appearance of the screen will differ as indicated in the discussion 
below. The effects of the various WITH phrase options of the format 3 ACCEPT 
statement are summarized in Section 4.8.3.3. 



4.8.1 FORMAT 1 ACCEPT STATEMENT 

Any of several system-defined data items may be obtained at execution time by 
use of the format 1 ACCEPT statement. 



The formats of the system-defined data items are: 

DATE — a six digit value of the form YYMMDD (year, month, day). Example: 
July 4, 1976 is 760704 

DAY - a five digit "Julian date" of the form YYNNN where YY is the two low 
order digits of year and NNN is the day-in-year number between 1 and 366, 
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TIME — an eight digit value of the form HHMMSSFF where HH is from 00 to 23, 
MM is fronn 00 to 59, SS is fronn 00 to 59, and FF is fronn 00 to 99; HH is the 
hour, MM is the minutes, SS is the seconds, and FF represents hundredths of a 
second. 

LINE NUMBER — a two digit value that represents the line (terminal) on which 
the program is currently running. In the COBOL-30 system, the value of LINE 
NUMBER is always 00. 

ESCAPE KEY — a two digit code generated by the key that terminated the most 
recently executed format 3 or format 4 ACCEPT statement. Identifier-1 can be 
interrogated to determine exactly which key was typed. Input may be 
terminated by any of the following keys, and cause the ESCAPE KEY value to be 
set as shown: 

Backtab (terminates only format 3 ACCEPTs) 99 

Escape 01 

Field-terminator (of the last 00 

field if format 4 ACCEPT is used) 

Function key 02-nn 

All key codes are defined in the CRT driver for the terminal being used (refer to 
Appendix A of the User's Guide). On most terminals, backtab may be entered as 
CONTROL-B or ",• escape is the ESCAPE or ALT key; field-terminator may be 
entered as CARRIAGE RETURN, LINE FEED, TAB, ENTER, NEW LINE or 
CONTROL-I; and the function keys are usually CONTROL-A, CONTROL-C, and 
CONTROL-X, generating ESCAPE KEY values of 02, 03, and 04 respectively. If 
input is terminated as a result of using the AUTO-SKIP option (i.e., no 
terminator key is struck), the ESCAPE KEY value is set to 00. 

identifier-1 should be an unsigned numeric integer whose length agrees with the 
content of the system-defined data item. If not, the standard rules for a MOVE 
govern storage of the source value in the receiving item (identifier-1). 



4.8.2 FORMAT 2 ACCEPT STATEMENT 

Format 2 of the ACCEPT statement is used to accept a string of input 
characters from a scrolling device such as a teletype or a CRT in scrolling 
mode. When the ACCEPT statement is executed, input characters are read from 
the console device until a carriage return is encountered, then a carriage 
return/line feed pair is sent back to the console. The input data string is 
considered to consist of all characters keyed prior to (but not including) the 
carriage return. 
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For a Format 2 ACCEPT with an alphanumeric receiving field, the input data 
string is transferred to the receiving field exactly as if it were being MOV Ed 
from an alphanumeric field of length equal to the number of characters in the 
string. (That is, left justification, space filling, and right truncation occur by 
default, and right justification and left truncation occur if the receiving field is 
described as JUSTIFIED RIGHTJ If the receiving field is alphanumeric-edited, it 
is treated as an alphanumeric field of equal length (as if each character in its 
PICTURE were "X"), so that no insertion editing will occur. 

For a Format 2 ACCEPT with a numeric or numeric-edited receiving field, the 
input data string is subjected to a validity test which depends on the PICTURE of 
the receiving field. (If the receiving field is described as COMP, its PICTURE is 
treated as "59(5)*' for purposes of this discussion,) The digits through 9 are 
considered valid anywhere in the input data string. 

The decimal point character (period or comma, depending on the DECIMAL 
POINT IS clause of the CONFIGURATION SECTION) is considered valid if: 

1. it occurs only once in the input data string, and 

2. if the PICTURE of the receiving field contains a fractional digit 
position, that is, a "9", "Z", "*", or floating insertion character which 
appears to the right of either an assumed decimal point ("V") or an 
actual decimal point (".'0. 

The operational sign characters %" and "-" are considered valid only as the first 
or last character of the input string and only if the PICTURE of the receiving 
field contains one of the sign indicators "S", "4.'^ "-", "CR'', or "D8". 

All other characters are considered invalid. If the input data string is invalid, 
the message "INVALID NUMERIC INPUT - PLEASE RETYPE" is sent to the 
console, and another input data string is read. 

When a valid input data string has been obtained, data is transferred to the 
receiving field exactly as if the instruction being executed were a MOVE to the 
receiving field from a hypothetical source field with the following 
characteristics: 

1. a PICTURE of the form S9...9V9...9 

2. USAGE DISPLAY 

3. a total length equal to the number of digits in the input data string 



CO8OL-80 Reference Manual - Release 4 64 

Procedure Division 

4. as many digit positions to the right of the assumed decimal point as 
there are digits to the right of the explicit decimal point in the input 
data string (zero if there is no decimal point in the input data string) 

5* current contents equal to the string of digits embedded in the input 
data string 

6, a separate sign with a current negative status if the input data string 
contains the character '*-", and a current positive status otherwise* 



4,aJ FORMAT 3 ACCEPT STATEMENT 

Format 3 of the ACCEPT statement is used to accept data into a field from a 
non-scrolling video terminal. The following syntax rules must be observed when 
the format 3 ACCEPT is used: 

1* identifier-3 must reference a data item whose length is less than or 
equal to 1920 characters 

2. the options SPACE-RLL and ZERO-FILL may not both be specified in 
the same ACCEPT statement 

3. the options LEFT-JUSTIFY and RIGHT-JUSTIFY may not both be 
specified within the same ACCEPT statement 

4. if identifier-3 is described as a numeric-edited item, the UPDATE 
option must not be specified 

5. the TRAILING-SIGN option may be specified only if identifier-3 Is 
described as an elementary numeric data item. If ldentifier-3 is 
described as unsigned, the TRAILING-SIGN option is ignored 

6. for alphanumeric or alphanumeric-edited identifier-3, the SPACE-FILL 
option is assumed if the ZERO-FILL option is not specified, and the 
LEFT-JUSTIFY option is assumed if the RIGHT-JUSTIFY option is not 
specified 

7. for numeric or numeric-edited identifier-3, the ZERO-FILL option is 
assumed if the SPACE-FILL option is not specified. 

4.8.3.1 Data Input Field 

The position-spec and receiving field (identifier-3) specifications of the format 3 
ACCEPT statement are used to define the location and characteristics of a data 
input field on the screen of the console video terminal. 
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Location of the Data Input Field 
The position-spec is of the form 



LIN 



I I integer-1 
integer-2 



COL 



integer-3 



integer-4 



The opening and closing parentheses and the comma and space separating the 
two major bracketed groups are required. The position-spec specifies the 
position on the console CRT screen at which the data input field will begin. LIN 
and COL are COBOL special registers. Each behaves like a numeric data item 
with USAGE COMP, but they may be referenced by every COBOL program 
without being declared in the DATA DIVISION, 

If LIN is specified, the data input field will begin on the screen row whose 
number is equal to the value of the LIN special regi'ster, incremented (or 
decremented) by integer-1 if "+ integer-1" (or "- integer-1**) is specified. If 
integer-2 is specified, the data input field will begin on the row whose number is 
integer-2* If neither LIN nor integer-2 is specified, the data input field will 
begin on the screen row containing the current cursor position. 

If COL is specified, the data input field will begin in the screen column whose 
number is equal to the value of the COL special register, incremented (or 
decremented) by integer-3 if % integer-3 (or "- integer-3") is specified. If 
integer-4 is specified, the data input field will begin in the screen column whose 
number is integer-4. If neither COL nor integer'4 is specified, the data input 
field will begin in the screen column containing the current cursor position. 

Characteristics of the Data Input Field 

The characteristics (other than position) of the data input field on the CRT 
screen are determined by the receiving field's PICTURE specification (which is 
treated as S9(5) in the case of an item whose USAGE is COMPUTATIONAL). For 
alphanumeric or alphanumeric-edited identifier-3, the data input field is simply a 
string of data input character positions starting at the screen location specified 
by position-spec. The length of the data input field in character positions is 
equal to the length of the receiving field in memory. 



COBOL-80 Reference Manual G(^ 

Procedure Division 



For numeric or numeric-edited identifier-3, the data input field may contain any 
or all of the following: integer digit positions, fractional digit positions, sign 
position, decimal point position. There will be one digit position for each "9", 
"2", "*", "P", or non-initial floating insertion symbol (a floating insertion symbol 
is a '*+", "-", or "$" which is not the last symbol in a PICTURE character string) 
in the PICTURE of identifier-3. Each digit position in the data input field is a 
fractional digit position if the corresponding PICTURE character is to the right 
of an assumed decimal point ("V") or actual decimal point (".") in the PICTURE 
of identifier-3. Otherwise it is an integer digit position. There will be one sign 
position if identifier-3 is described as signed, and no sign position otherwise. 
There will be one decimal point position if there is at least one fractional digit 
position, and no decimal point position otherwise. 

The data input positions which are defined will occupy successive character 
positions on the CRT screen beginning with the position specified by 
position-spec. If TRAILING-SIGN is specified in the ACCEPT statement, the 
data input positions will be in the following sequence: integer digit positions (if 
any), decimal point position (if any), fractional digit positions (if any), sign 
position (if any). If TRAILING-SIGN is not specified, the data input positions 
will be in the following sequence: sign position (if any), integer digit positions (if 
any), decimal point position (if any), fractional digit positions (if any). 



4.3,3.2 Data Input and Data Transfer 

A character entered into the data input field by the terminal operator may be 
treated either as an editing character, a terminator key or a data character. 
When a terminator key is typed, the ACCEPT is terminated and the ESCAPE 
KEY value is set as described in section 4.8,1. This value can be interrogated by 
using a format 1 ACCEPT statement FROM ESCAPE KEY. 

The editing characters are line-delete, forward-space, backspace, and rubout. 
On most terminals, these characters may be entered as control-U, controi-F, 
control-H, and DEL (or RUB) respectively. The action of the editing characters 
is described later in this section; for now, only data characters will be considered. 

See the CO8OL-80 User's Guide for further information on the definition of 
editing and terminator characters. 

Alphanumeric Receiving Field 

Consider first the execution of the format 3 ACCEPT statement with an 
alphanumeric or alphanumeric-edited receiving field. An alphanumeric-edited 
receiving field is treated as an alphanumeric field of the same length (as if every 
character in its PICTURE were "X"). Specifically, no insertion editing will occur. 
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The initial appearance of the data input field depends on the specifications in the 
WITH phrase of the ACCEPT statement. If UPDATE is specified, the current 
contents of identifier-3 are displayed in the input field. In this case ail data 
input positions will be treated as if they were keyed by the terminal operator. If 
UPDATE is not specified, but PROMPT is specified, a period (".") is displayed in 
each input data position. If neither UPDATE nor PROMPT is specified, the data 
input field is not changed. The cursor is placed in the first data input position, 
and characters are accepted as they are keyed by the operator until a terminator 
character (normally carriage return) is encountered. If AUTO-SKIP is specified 
in the ACCEPT statement, the ACCEPT will also be terminated if the operator 
keys a character into the last (rightmost) data input position. 

As each input character is received, it is echoed to the CRT screen, except that 
non-displayable characters are echoed as "?". If ail positions of the data input 
field are filled, additional input is ignored until a terminator character or editing 
character (listed above) is encountered. If RIGHT-JUSTIFY was specified in the 
ACCEPT statement, the operator-keyed characters are shifted to the rightmost 
positions of the data input field when the ACCEPT is terminated. All unkeyed 
character positions are filled on termination; the fill character is either space (if 
SPACE- FILL is in effect) or zero (if ZERO-FILL was specified). 

The contents of the receiving field will be the same set of characters as appear 
in the input field; however, the justification of operator-keyed characters will be 
controlled by the JUSTIFIED specification in the receiving field's data 
description, not by the RIGHT- or LEFT-JUSTIFY option of the ACCEPT. 
Excess positions of the receiving field will be filled with spaces or zeroes based 
on the SPACE- or ZERO-FILL specification in the ACCEPT statement. 

Numeric Receiving Field 

Next, consider the execution of a format 3 ACCEPT statement with a numeric 
or numeric-edited receiving field. As described above, the data input field on 
the console CRT screen may contain integer digit positions, fractional digit 
positions, or both. First assume that both are present; the other cases will be 
treated as variations. 
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As with the alphanumeric ACCEPT, the data input field may be initialized in a 
way determined by the WITH options specified in the ACCEPT statement. If 
UPDATE is specified (not permitted for a numeric-edited receiving field), the 
integer and fractional parts of the data input field will be set to the integer and 
fractional parts of the decimal representation of the initial value of the 
receiving field, with leading and trailing zeroes included, if necessary, to fill all 
digit positions. Except for leading zeroes, these initialization characters are 
treated as operator-keyed data. If UPDATE is not specified, but PROMPT is 
specified, a zero will be displayed in each input digit position. In either of these 
cases (UPDATE or PROMPT) a decimal point will be displayed at the decimal 
point position. 

If neither UPDATE nor PROMPT is specified, the input field on the screen will 
not be initialized, except for the sign position. The sign position is always 
initialized positive except when UPDATE is specified, in which case it is 
initialized according to the sign of the current contents of the receiving field. 
On most systems, a positive sign position is shown as a space, and a negative sign 
position is shown as a minus sign. 

The cursor is initially placed in the rightmost integer digit position, and 
characters are accepted one at a time as they are keyed by the operator, A 
received character may be treated in one of several ways. If the incoming 
character is a digit, previously keyed digits are shifted one position to the left in 
the input field and the new digit is displayed in the rightmost integer digit 
position. If all integer digit positions have not been filled, the cursor remains on 
the rightmost digit position and another character is accepted. If the entire 
integer part of the input field has been filled and AUTO-SKIP was specified, the 
integer part is terminated and the cursor is moved to the leftmost fractional 
digit position. If the integer part has been filled and AUTO-SKIP was not 
specified, the cursor is moved to the decimal point position, and any further 
digits keyed are ignored until the integer part is terminated with a decimal point. 

If the character entered is one of the sign characters ">" or *'-'*, the sign position 
is changed to a positive or negative status respectively. Cursor position is not 
affected. 

If the character entered is a decimal point character, the integer part is 
terminated and the cursor is moved to the leftmost fractional digit position. 

If the character entered is a field terminator (normally carriage-return), the 
ACCEPT is terminated and the cursor is turned off. Any other character is 
ignored. 
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When the integer part is terminated, the cursor is placed in the leftmost 
fractional digit position, and operator-keyed characters are again accepted. 
Digits are simply echoed to the terminal. The sign characters 'V" and "-'* are 
treated exactly as they were while integer part digits were being entered. The 
field terminator character terminates the ACCEPT. (If AUTO-SKIP is in effect, 
filling the entire fractional part also terminates the ACCEPT.) Other characters 
are ignored. After all digit positions of the fractional part have been filled, 
further digits are also ignored. 

If no fractional digit positions are present, the decimal point is ignored as an 
input character, and entry of integer part digits may be terminated only by 
terminating the entire ACCEPT. If no integer digit positions are present, the 
cursor is initially placed in the leftmost fractional digit position and entry of the* 
fractional part digits proceeds as described above. 

On termination of the format 3 ACCEPT of a numeric or numeric-edited item, 
data is transferred to the receiving field. The exact form of the data in the 
receiving field after execution of the ACCEPT is as described in the last 
paragraph of the discussion of the format 2 ACCEPT, where the role of the 
"input data string" mentioned in that paragraph is taken by the string of 
characters displayed in the data input field. After termination, if SPACE-FILL 
is in effect, leading zeroes in the integer part of the data input field (not in the 
receiving field) will be replaced by spaces, and the leading operational sign, if 
present, will be moved to the rightmost space thus created. 

Editing Characters 

The editing characters (line-delete, forward-space, backspace, and rubout) may 
be used to change data which has already been keyed (or supplied by the COBOL 
runtime system as a result of a WITH UPDATE specification). Entering the 
line-delete character will cause the ACCEPT to be restarted and all data keyed 
by the operator or initially present in the receiving field to be lost. The data 
input field on the console screen will be re-initialized if PROMPT is in effect. 
Otherwise, the data input field will be filled with spaces or zeroes according to 
the SPACE-FILL or ZERO-FILL specification. 
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Typing the forward-space or backspace characters will move the cursor forward 
or back one data input position in the case of an alphanumeric or 
alphanumeric-edited receiving field, or one digit position in the case of a 
numeric or numeric-edited receiving field. In no case, however, will the 
forward-space or backspace characters move the cursor outside the range of 
positions including (1) the positions already keyed by the operator (or filled by 
COBOL runtime support when WITH UPDATE is specified), and (2) the rightmost 
data input position which the cursor has occupied during the execution of this 
ACCEPT, If the cursor is moved to a position of this range other than the 
rightmost, and a legal data character is entered, it is displayed at the current 
cursor position and the cursor is moved forward one data position (alphanumeric 
or alphanumeric-edited) or digit position (numeric or numeric-edited). 

Typing the rubout character effectively cancels the last data character entered. 
The cursor is moved back one data position (digit position if the receiving field is 
numeric or numeric-edited) and a fill character (space or zero) is displayed under 
the cursor (except when the cursor is to the left of the decimal point for a 
numeric ACCEPT. Then no fill character is displayed and the cursor is not 
moved, but the digit at the cursor position is deleted and all digits to the left of 
it are shifted one position to the right.) The rubout character has no effect 
unless the cursor is in position to accept a new data character; in other words, it 
has no effect if backspace character(s) have been used to move the cursor back 
over already keyed positions. 

4.8.3.3 WITH Phrase Summary 

The following list summarizes the effects of the WITH phrase specifications for a 
format 3 ACCEPT with an alphanumeric or alphanumeric-edited receiving field: 

1. SPACE-FILL causes unkeyed character positions of the data input 
field and the receiving field to be space-filled when the ACCEPT is 
terminated. 

2. ZERO-FILL causes unkeyed character positions of the data input 
field and the receiving field to be set to ASCII zeroes when the 
ACCEPT is terminated. 

3. LEFT-JUSTIFY is treated by this compiler as commentary. 

4. RIGHT-JUSTIFY causes operator-keyed characters to occupy the 
rightmost positions of the data input field (on the screen) after the 
ACCEPT is terminated. Note that the justification of transferred 
data in the receiving field is controlled by the JUSTIFIED declaration 
or default of the receiving field's data description, not by the WITH 
RIGHT-JUSTIFY phrase. 
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5* PROMPT causes the data input field on the screen to be set to all 
periods (".") before input characters are accepted. 

6. UPDATE causes the data input field to be initialized with the initial 
contents of the receiving field and the initial data to be treated as 
operator-keyed data. 

7. LENGTH-CHECK causes a field terminator character to be ignored 
unless every data input position has been filled. 

8. AUTO-SKIP forces the ACCEPT to be terminated when all data input 
positions have been filled. A terminator character explicitly keyed 
has its usual effect. 

9. BEEP causes an audible alarm to sound when the ACCEPT is 
initialized and the system is ready to accept operator input. 

The following list summarizes the effects of the WITH phrase specifications for 
the format 3 ACCEPT with a numeric or numeric-edited receiving field: 

1. 3^ACE-FILL causes unkeyed digit positions of the data input field 
(not of the receiving field) to the left of the (possibly implied) 
decimal point to be space-filled when the ACCEPT is terminated and 
any leading operational sign to be displayed in the rightmost space 
thus created. 

2. ZERO-FILL causes all unkeyed digit positions of the data input field 
to be set to zero when the ACCEPT is terminated. 

3. LEFT-JUSTIFY and RIGHT-JUSTIFY have no effect for a numeric or 
numeric-edited receiving field. 

4. TRAILING-SIGN causes the operational sign to appear as the 
rightmost position of the data input field. Ordinarily the sign is the 
leftmost position of the field. 

5. PROMPT causes the data input field positions to be initialized as 
follows before input characters are accepted: digit positions to zero, 
decimal point position (if any) to the decimal point character, and 
sign position (if any) to space. 

6. UPDATE causes the data input field to be initialized to the current 
contents of the receiving field and this initial data to be treated like 
operator-keyed data. 
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9. 



LENGTH-CHECK causes a received decimal point character to be 
ignored unless all integer digit positions have been keyed and a field 
terminator character to be ignored unless all digit positions have 
been keyed, 

AUTO-SKIP causes the integer part of the ACCEPT to be terminated 
when all integer digit positions have been keyed and the entire 
ACCEPT to be terminated when all digit positions have been keyed. 

BEEP causes an audible alarm to sound when the ACCEPT is 
initialized and the system is ready to accept operator input. 



4,8.4 Examples Using the Format 3 ACCEPT Statement 



.Example 1 : 



Receiving Field: 

OS RS-DISCOUNT PIC X (&) . 

Initial Contents : 
ABCDEFCH 

ACCEPT Statement: 

ACCEPT (In 1) RS-DISCOUNT liJITH PROHPT 


Set-up 

prior to executing 


At Start of ACCEPT: 

Operator Enters N : 
N^ 

Operator Enters ONE: 
NONE.. . . 

Operator Enters Carriage Return: 
NONEJz$)j5)2J]z5 


Executing 
the ACCEPT 


Final Contents 

of Receiving Field: 

NONE]z^)zJ)z$}:J 


Result 
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Example 2 



Receiving Field: 

10 VEND-NAME PIC X{ia) . 

Initial Contents: 
ACnEJzJyiDGETS 

ACCEPT Statement: 

ACCEPT (1. 1) VEND-NAHE 
UITH PROnPT UPDATE. 


Set-up 

prior to executing 


At Start of ACCEPT: 
ACnEjziUIDGETS 

(If operator enters carriage 
return here, the receiving 
field will not be changed.) 

Operator Enters Line-delete: 


Executing 
the ACCEPT 


Operator Enters XYZ: 

YVT 


Operator Enters Carriage Return: 


Final Contents 

of Receiving Field: 

XYZ ]61i6]6]6]6]6]61^]6 


Result 
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Example 3 : 



Receiving Field: 

OS CREDIT PIC S1(M)V1T. 

Initial Contents: 

+ 

mill 

ACCEPT statement: 

ACCEPT (LIN + ^-, COL - 3) Ci^EDIT 
yiTH PROnPT TRAILING-SIGN. 


Set-up 

prior to executing 


At Start of ACCEPT: 

ooag.ODji 

Operator Enters fl: 

aaaa.ao]d 

Operator Enters 7 : 
0037.00)2$ 

Operator Enters -: 
0057.00- 

Operator Enters (a : 

oa7b.oo- 

Operator Enters N : 

oa7b.oo- 

Operator Enters . : 

0fl7t. go- 
Operator Enters S : 

oa7b.sg- 

Operator Enters Carriage Return: 
0a7t. so- 


Executing 
the ACCEPT 


Final Contents 

of Receiving Field: 

0a7b^S0 


Result 
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4.a,5 FORMAT 4 ACCEPT STATEMENT 

Format 4 of the ACCEPT statement causes a transfer of information from the 
operator's console to all TO and/or USING fields specified in the SCREEN 

SECTION definition of screen-name (or screen items subordinate to 

screen-name.) Screen items having only a VALUE literal or a FROM clause have 
no effect on the operation of the ACCEPT statement. Each transfer consists of 
an implicit format 3 ACCEPT of a field defined by the appropriate screen item's 
PICTURE foUowed by an implicit MOVE to the associated TO or USING field. 
When the ACCEPT is terminated, the ESCAPE KEY value is set as described 
below and in section 4.8.1. This value can be interrogated by using a format 1 
ACCEPT statement FROM ESCAPE KEY. Fields are ACCEPTed in the order in 
which they are defined under screen-name in the SCREEN SECTION. This order 
can be changed by use of the backtab key, as described below, but the position of 
the field on the screen does not affect the order. 

If an escape key is typed during data input, the entire ACCEPT is terminated 
without moving the current field to the associated TO or USING item, the 
ESCAPE KEY value is set to 01, and the ON ESCAPE statement is executed. If 
a function key is typed, the appropriate ESCAPE KEY value is set and the entire 
ACCEPT is terminated. If a field-terminator key (carriage return, tab, etc.) is 
typed, the ESCAPE KEY value is set to 00 and the cursor moves to the next 
input field defined under screen-name, if one exists. If the current field is the 
last field, the entire ACCEPT is terminated. If the backtab key is typed, the 
current field is terminated and the cursor moves to the previous input field 
defined under screen-name. If the current field is the first field, the cursor does 
not move from that field. When a field is terminated by a function key, 
field-terminator key, or backtab key, the contents of the current field are moved 
to the associated TO or USING item, except in the case where no data 
characters and no editing characters have been entered in that field. This allows 
the operator to tab forward or backward through the input fields without 
affecting the contents of the receiving items. 

All the editing and validation features described in section 4.8.3.2 for the format 
3 ACCEPT apply to the format 4 ACCEPT as well. Several SCREEN SECTION 
specifications listed in section 3.17 correspond to the format 3 ACCEPT options: 
AUTO corresponds to AUTO- SKIP; BELL corresponds to BEEP; and JUSTIFIED 
corresponds to RIGHT-JUSTIFY. Furthermore, if an input field specifies the 
USING clause or both a FROM and TO clause, the ACCEPT will be executed with 
the UPDATE option. Format 4 ACCEPT statements always use the PROMPT 
and TRAILING- SIGN options when executing the individual format 3 ACCEPTS. 
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If the screen item's PICTURE specifies a numeric-edited or alphanumeric-edited 
input field, the ACCEPT is executed as if the field were numeric or 
alphanumeric, respectively. When the field is terminated the data is edited 
according to the PICTURE and redisplayed in the specified screen position. In 
this case, the JUSTIFIED clause has no effect. 

Moves from screen fields to receiving items follow the standard COBOL-80 rules 
for MOVE statements, except that moves from numeric-edited fields are 
allowed. In this case, the data is input as if the field were numeric and the move 
uses only the sign, decimal point and digit characters. 

The format 4 ACCEPT does not cause the display of any text or prompting label 
information. See the discussion of DISPLAY in section 4.9. 



4.9 DISPLAY STATEMENT 

The DISPLAY statement provides the capability of outputting low-volume data 

at runtime without the overhead of file definition. The format of the DISPLAY 

statement is: 

\ 

... [UPON mnemonic-name] 



DISPLAY f< [position-spec] 



fupositic 



identifier^ 

literal 

ERASE 



[screen-name] 
The DISPLAY statement must be coded in accordance with the following rules: 

1. identifier must reference a data item whose length is less than or 
equal to 1920 characters. 

2. mnemonic-name must be defined in the PRINTER IS clause of the 
SPECIAL-NAMES paragraph of the CONFIGURATION SECTION 

3. screen-name must be defined in the SCREEN SECTION of the DATA 
DIVISION. 
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The DISPLAY statement will cause output to be sent to the system console 
device unless UPON mnemonic-name is specified, in which case output will be 
sent to the printer. Each display-item (that is, each occurrence of identifier, 
literal, ERASE, or screen-name) will be processed in turn as described in the 
paragraphs below; then, if neither position-spec nor screen-name is coded in the 
entire DISPLAY statement, a carriage return/line-feed pair will be sent to the 
receiving device. 



4.9,1 Position-spec 

For each display-item, if position-spec is specified, the cursor is positioned prior 
to the transfer of data for the item, position-spec is of the form: 



LIN 



integer-1 



integer-2 



COL 



integer-3 



integer-4 



The opening and closing parentheses and the comma and space separating the 
two major bracketed groups are required. Position-spec specifies the position on 
the console CRT screen at which the cursor will be placed. LIN and COL are 
COBOL special registers. Each behaves like a numeric data item with USAGE 
COMP, but they may be referenced by every COBOL program without being 
declared in the DATA DIVISION. 

If LIN is specified, the cursor will be placed on the screen row whose number is 
equal to the value of the LIN special register, incremented (or decremented) by 
integer-1 if "+ integer-l" (or "- integer-TO is specified. If integer-2 is specified, 
the cursor will be placed on the row whose number is integer-2. If neither LIN 
nor integer-2 is specified, the cursor will be placed on the screen row containing 
the current cursor position. 

If COL is specified, the cursor will be placed in the screen column whose number 
is equal to the value of the COL special register, incremented (or decremented) 
by integer-3 if "+ integer-3" (or "- integer-3") is specified. If integer-4 is 
specified, the cursor will be placed in the screen column whose number is 
integer-4. If neither COL nor integer-4 is specified, the cursor will be placed in 
the screen column containing the current cursor position. 
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4,9.2 Identifier, Literal, and ERASE 

If identifier or literal is specified for a given display-item, the contents of 
identifier or the value of literal are sent to the receiving device. Since the data 
transfer occurs without conversion or reformatting, it is recommended that 
numeric data be moved to numeric-edited fields for purposes of DISPLAY, 

If ERASE is specified and if position-spec is coded for this or a previous 
display-item, the console screen will be cleared from the current cursor position 
to the end of the screen. The initial cursor position for the next display-item 
will be that specified by the position-spec coded in the ERASE display-item, if 
present, or the position in which the cursor was left by the previous 
display-item. If ERASE is specified and no position-spec has been encountered 
up to this point in the DISPLAY statement, no action will be taken. 



4,9.3 Screen-name 

The DISPLAY screen-name statement causes a transfer of information from 
screen-name (or each elementary screen item subordinate to screen-name) to the 
console CRT screen. For each such screen item having a VALUE, FROM, or 
USING specification, the specified literal or field is the source of the displayed 
data. For a field having only a TO clause, the effect is as if FROM ALL "," 
(period) had been specified. The source data is MOV Ed implicitly to a temporary 
item defined by the appropriate screen item's PICTURE (or by the length of the 
data in the case of a VALUE literal). Then an implied identifier-type DISPLAY 
of the constructed temporary is executed as modified by the positioning and 
control clauses coded in the definition of the appropriate screen item. See 
section 3,17 (SCREEN SECTION), 
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4.10 PERFORM STATEMENT 

The PERFORM statement permits the execution of a separate body of program 
steps. Two formats of the PERFORM statement are available: 



Option 1 

n integer 
PERFORM range j data-name 1 TIMES 



Option 2 



(index-name) 
PERFORM range [ VARYING \data-name j FROM 

amount-1 BY amount-2] UNTIL condition. 

(A more extensive version of option 2 is available for varying 2 or 3 items 
concurrently, as explained in Appendix VI.) 

In the above syntactical presentation, the following definitions are assumed: 

1. Range is a paragraph-name, a section-name, or the construct 
procedure-name- 1 THRU procedure-name-2. (THROUGH is 
synonymous with THRU.) If only a paragraph-name is specified, the 
return is after the paragraph's last statement. If only a section-name 
is specified, the return is after the last statement of the last 
paragraph of the section^ If a range is specified, control is returned 
after the appropriate last sentence of a paragraph or section. These 
return points are valid only when a PERFORM has been executed to 
set them up; in other cases, control will pass right through. 

2. The generic operands amount-1 and amount-2 may be a numeric 
literal, index-name, or data-name. In practice, these amount 
specifications are frequently integers, or data-names that contain 
integers, and the specified data-name Is used as a subscript within 
the range. 

In Option 1, the designated range is performed a fixed number of times, as 
determined by an integer or by the value of an integer data-item. If no "TIMES'* 
phrase is given, the range is performed once. When any PERFORM has finished, 
execution proceeds to the next statement following the PERFORM statement. 
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In Option 2, the range is performed a variable number of times, in a step-wise 
progression, varying from an initial value of data-name = amount-1, with 
increments of amount-2, until a specified condition is met, at which time 
execution proceeds to the next statement after the PERFORM. 

The condition in an Option 2 PERFORM is evaluated prior to each attempted 
execution of the range. Consequently, it is possible to not PERFORM the range, 
if the condition is not met at the outset. Similarly, in Option 1, if data-name <0, 
the range is not performed at all. 

At run-time, it is illegal to have concurrently active PERFORM ranges whose 
terminus points are the same. 



4.11 EXIT STATEMENT . 

The EXIT statement is used where it is necessary to provide an endpoint for a 
procedure. 

The format for the EXIT statement is: 

EXIT 

EXIT must appear in the source program as a one-word paragraph preceded by a 
paragraph-name and followed by a period. An exit paragraph provides an 
end-point to which preceding statements may transfer control if it is decided to 
bypass some part of a section. 



4.12 ALTER STATEMENT 

The ALTER statement is used to modify a simple (non-depending) GO TO 
statement elsewhere in the Procedure Division, thus changing the sequence of 
execution of program statements. 

The ALTER statement general format is: 

ALTER paragraph TO [PROCEED TO] procedure-name 

Paragraph (the first operand) must be a COBOL paragraph that consists of only a 
simple GO TO statement; the ALTER statement in effect replaces the former 
operand of that GO TO by procedure-name. Consider the ALTER statement in 
the context of the following program segment. 

GATE. GO TO MF-OPEN. 

MF-OPEN. OPEN INPUT MASTER-RLE. 

ALTER GATE TO PROCEED TO NORMAL. 
NORMAL. READ MASTER-FILE, AT END GO TO EOF-MASTER. 

Examination of the above code reveals the technique of '^shutting a gate," 
providing a one-time initializing program step. 



CO8OL-80 Reference Manual 
Procedure Division 



Release 4 



81 



4,13 F STATEMENT 

The IF statennent permits the programmer to specify a series of procedural 
statements to be executed in the event a stated condition is true. Optionally, an 
alternj^tive series of statements may be specified for execution if the condition 
is false. The general format of the IF statement is: 



IF condition (statement(s)-l ] 

NEXT SENTENCE 



ELSE |statement(s)-2 

I NEXT SENTENCE 



The IF statement must be followed immediately by a period. 
Examples of IF statements: 

1. IF BALANCE = GO TO NOT-FOUND. 

2. F T LESS THAN 5 NEXT SENTENCE ELSE GO TO T-1-4. 

3. IF ACCOUNT.RELD = SPACES OR NAME = SPACES ADD 1 TO 
SKP-COUNT ELSE GO TO BYPASS. 

The first series of statements is executed only if the designated condition is 
true. The second series of statements (ELSE part) is executed only if the 
designated condition is false. Refer to Appendix III for discussion of nested IF 
statements. 

Regardless of whether the condition is true or false, the next sentence is 
executed after execution of the appropriate series of statements, unless a GO 
TO is contained in the imperatives that are executed, or unless the nominal flow 
of program steps is superseded because of an active PERFORM statement. 

4.13.1 Conditions 

A condition is either a simple condition or a compound condition. The four 
simple conditions are the relational, class, condition-name, and sign condition 
tests. A simple relational condition has the following structure: 

operand-1 relation operand-2 

where "operand" is a data-name, literal, or figurative-constant. 

A compound condition may be formed by connecting two conditions, of any sort, 
by the logical operator AND or OR, e.g., A < B OR C = D. Refer to Appendix I 
for further permissible forms involving parenthesization, NOT, or "abbreviation." 
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The simplest "simple relations" have three basic forms, expressed by the 
relational symbols equal to, less than, or greater than (i,e., = or < or >). 

Another form of simple relation that may be used involves the reserved word 
NOT, preceding any of the three relational symbols. In summary, the six simple 
relations in conditions are: 



Relation Meaning 

= equal to 

< less than 

> greater than 

NOT = not equal to 

NOT < greater than or equal to 

NOT > less than or equal to 

It is worthwhile to briefly discuss how relation conditions can be compounded. 
The reserved words AND or OR permit the specification of a series of relational 
tests, as follows: 

1. Individual relations connected by AND specify a compound condition 
that is met (true) only if all the individual relationships are met. 

2. Individual relations connected by OR specify a compound condition 
that is met (true) if any one of the individual relationships is met. 

The following is an example of a compound relation condition containing both 
AND and OR connectors. Refer to Appendix I for formal specification of 
evaluation rules. 

F X = Y AND FLAG = 'Z' OR SWITCH = GO TO PROCESSING. 

In the above example, execution will be as follows, depending on various data values. 



Data Value 


Does Execution Go 
to PROCESSING? 


X 


Y 


FLAG SWITCH 


10 


10 


•Z' 


1 


Yes 


10 


11 


•Z' 


1 


No 


10 


11 


•z* 





Yes 


10 


10 


p, 


1 


No 


6 


3 


,p, 





Yes 


6 


6 


.p. 


1 


No 
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Usages of reserved word phrasings EQUAL TO, LESS THAN, and GREATER 
THAN are accepted equivalents of =< > respectively. Any form of the relation 
may be preceded by the word IS, optionally. 

Before discussing class-test, sign-test, and condition-name conditions, methods 
of performing comparisons will be discussed. 

Numeric Comparisons; The data operands are compared after alignment of their 
decimal positions. The results are as defined mathematically, with any negative 
values being less than zero, which in turn is less than any positive value. An 
index-name or index data item (see Chapter 6) may appear in a comparison. 
Comparison of any two numeric operands is permitted regardless of the formats 
specified in their respective USAGE clauses, and regardless of length. 

Character Comparisons; Non-equal-length comparisons are permitted, with 
spaces being assumed to extend the length of the shorter item, if necessary. 
Relationships are defined in the ASCII code; in particular, the letters A-Z are in 
an ascending sequence, and digits are less than letters. Group items are treated 
simply as character strings when compared. Refer to Appendix IV for ail ASCII 
character representations. 

Returning to our discussion of simple conditions, there are three additional forms 
of a simple condition, in addition to the relational form, namely: class test, 
condition-name test, and sign test. 

A class test condition has the following syntactical format: 

[ numeric ] 

data-name IS [NOT] i ALPHABETIC J 

This condition specifies an examination of the data item content to determine 
whether all characters are proper digit representations regardless of any 
operational sign (when the test is for NUMERIC), or only alphabetic or blank 
space characters (when the test is for ALPHABETIC). The NUMERIC test is 
valid only for a group, decimal, or character item (not having an alphabetic 
PICTURE). The ALPHABETIC test is valid only for a group or character item 
(PICTURE an-form). 

A sign test has the following syntactical format: 

data-name IS [ NOT ] NEGATIVE I ZERO I POSITIVE 

This test is equivalent to comparing data-name to zero in order to determine the 
truth of the stated condition. 

In a condition-name test, a conditional variable is tested to determine whether 
its value is equal to one of the values associated with the condition-name. A 
condition-name test is expressed by the following syntactical format: 

condition-name 
where condition-name is defined by a level 88 Data Division entry. 
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4.14 OPEN STATEMENT (Sequential I-O) 

The OPEN statement must be executed prior to commencing file processing. 
The general format of an OPEN statement is: 



OPEN 



( INPUT 

I-O 

OUTPUT 
i EXTEND J 



file-name..* 



For a sequential INPUT file, opening initiates reading the file's first records into 
memory, so that subsequent READ statements may be executed without waiting. 

For an OUTPUT file, opening makes available a record area for development of 
one record, which will be transmitted to the assigned output device upon the 
execution of a WRITE statement. An existing file which has the same name will 
be superceded by the file created with OPEN OUTPUT. 

An OPEN I-O statement is valid only for a DISK file; it permits use of the 
REWRITE statement to modify records which have been accessed by a READ 
statement. The WRITE statement may not be used In 1-0 mode for files with 
sequential organization. The file must exist on disk at OPEN time; it cannot be 
created by OP EN I-O. 

When the EXTEND phrase is specified, the OPEN statement positions the file 
immediately following the last logical record of that file. Subsequent WRITE 
statements referencing the file will add records to the end of the file. Thus, 
processing proceeds as though the file had been opened with the OUTPUT phrase 
and positioned at its end. EXTEND can be used only for sequential or line 
sequential files. 

Failure to precede (in terms of time sequence) file reading or writing by the 
execution of an OPEN statement is an execution-time error which will cause 
abnormal termination of a program run. See the COBOL-80 User's Guide. 
Furthermore, a file cannot be opened if it has been CLOSEd "WITH LOCK." 

Sequential files opened for INPUT or I-O access must have been written in the 
appropriate format described in the User's Guide for such files. 
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4,15 READ STATEMENT (Sequential I-O) 

The READ statement makes available the next logical data record of the 
designated file from the assigned device, and updates the value of the FILE 
STATUS data item, if one was specified. The general format of a READ 
statement is: 

READ file-name RECORD [INTO data-name] 
[at end imperative statement]. 

Since at some time the end-of-file will be encountered, the user should include 
the AT END clause. The reserved word END is followed by any number of 
imperative statements, all of which are executed only if the end-of-file situation 
arises. The last statement in the AT END series must be followed by a period to 
indicate the end of the sentence. If end-of-file occurs but there is no AT END 
clause on the READ statement, an applicable Declarative procedure is 
performed. If neither AT END nor Declarative exists and no FILE STATUS item 
is specified for the file, the program is aborted with a run-time error. 

When a data record to be read exists, successful execution of the READ 
statement is immediately followed by execution of the next sentence. 

When more than one level-01 item is subordinate to a file description, these 
records share the same storage area. Therefore, the user must be able to 
distinguish between the types of records that are possible, in order to determine 
exactly which type is currently available. This is accomplished with a data 
comparison, using an IF statement to test a field which has a unique value for 
each type of record. 

The INTO option permits the user to specify that a copy of the data record is to 
be placed into a designated data field in addition to the file's record area. The 
data-name must not be defined in the File Section. 

Also, the INTO phrase should not be used when the file has records of various 
sizes as indicated by their record descriptions. Any subscripting or indexing of 
data-name is evaluated after the data has been read but before it is moved to 
data-name. Afterward, the data is available in both the file record and 
data-name. 

In the case of a blocked input file (such as disk files), not every READ statement 
performs a physical transmission of data from an external storage device; 
instead, READ may simply obtain the next logical record from an input buffer. 



If the actual record is shorter than the file record area, the file record area is 
padded on the right with spaces. 
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4.16 WRITE STATEMENT (Sequential I-O) 

The general format of a WRITE statement is: 

WRITE record-name [ FROM data-name-1] 

'( AFTER \ ADVANCING (operand LINE(S)) 
I BEFORE 1 1 PAGE ) 

[AT I END-OF-PAGE 1 imperative-statement] 
JECP ) 

Ignoring the ADVANCING option for the moment, we proceed to explain the 
main functions of the WRITE statement. 

In COBOL, file output is achieved by execution of the WRITE statement. 
Depending on the device assigned, "written" output may take the form of printed 
matter or magnetic recording on a floppy disk storage medium. The associated 
file must be open in the OUTPUT or I-O mode at time of execution of a WRITE 
statement. 

Record-name must be one of the level 01 records defined for an output file, and 
may be qualified by the filename. The execution of the WRITE statement 
releases the logical record to the file and updates its FILE STATUS item, if one 
is defined. 

If the data to be output has been developed in Working-Storage or in another area 
(for example, in an input file's record area), the FROM suffix permits the user to 
stipulate that the designated data (data-name-1) is to be copied into the 
record-name area and then output from there. Record-name and data-name-1 
must refer to separate storage areas. 

When an attempt is made to write beyond the externally defined boundaries of a 
sequential file, a Declarative procedure will be executed (if available) and the 
FILE STATUS (if available) will indicate a boundary violation. If neither is 
available, a fatal runtime error occurs. 

The ADVANCING option is restricted to line printer output files, and permits 
the programmer to control the line spacing on the paper in the printer. Operand 
is either an unsigned integer literal or data-name; values from to 120 are 
permitted: 
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Integer Carriage Control Action 



No spacing 

1 Nornnai single spacing 

2 Double spacing 

3 Triple spacing 



Single spacing (I.e*, "after advancing 1 line") is assunned if there is no BEFORE or 
AFTER option in the WRITE statement. 

Use of the key word AFTER implies that the carriage control action precedes 
printing a line, whereas use of BEFORE implies that writing precedes the 
carriage control action. If PAGE is specified, the data is printed BEFORE or 
AFTER the printer is repositioned to the next physical page. However, if a 
LINAGE clause is associated with the file, the repositioning Is to the first line 
that can be written on the next logical page as specified in the LINAGE clause. 

If the END-OF-PAGE phrase is specified, the LINAGE clause must be specified 
in the file description entry for the associated file. EOP is equivalent to 
END-OF-PAGE. 

An end-of-page condition is reached whenever a WRITE statement with the 
END-OF-PAGE phrase causes printing or spacing within the footing area of a 
page body. This occurs when such a WRITE statement causes the 
LINAGE-COUNTER to equal or exceed the value specified by the FOOTING 
value, if specified. In this case, after the WRITE statement is executed, the 
imperative statement in the END-OF-PAGE phrase is executed. 

A "page overflow" condition is reached whenever a WRITE statement cannot be 
fully accommodated within the current page body. This occurs when a WRITE 
statement would cause the LINAGE-COUNTER to exceed the value specified as 
the size of the page body in the LINAGE clause. In this case, the record is 
printed before or after (depending on the phrase used) the printer is repositioned 
to the first line of the next logical page. The imperative statement in the 
END-OF-PAGE clause, if specified, is executed after the record is written and 
the printer has been repositioned. 

Clearly, if no FOOTING value is specified in the LINAGE clause, or if the 
end-of-page and overflow conditions occur simultaneously, then only the 
overflow condition is effective. 
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4,17 CLOSE STATEMENT (Sequential lO) 

Upon completion of the processing of a file, a CLOSE statement must be 
executed, causing the system to make the proper disposition of the file. 
Whenever a file is closed, or has never been opened, READ, REWRITE, or WRITE 
statements cannot be executed properly; a runtime error would occur, aborting 
the run. 

The general format of the CLOSE statement is: 

CLOSE {file-name [WITH LOCK ] } .,. 

If the LOCK phrase is used, the runtime system will cause subseuqent OPENs of 
the file to fail during the current job. If LOCK is not specified immediately 
after a file-name, then that file may be re-OPENed later in the program, if the 
program logic dictates the necessity. 

An attempt to execute a CLOSE statement for a file that is not currently open is 
a runtime error, and causes execution to be discontinued. 

Examples of CLOSE statements: 

CLOSE MASTER-FILE-IN WITH LOCK, WORK-FILE; 

CLOSE PRINT-RLE, TAX-RATE-FILE, JOB-PARAMETERS WITH LOCK 



4.18 REWRITE STATEMENT (Sequential I-O) 

The REWRITE statement replaces a logical record on a sequential disk file. The 
general format is: 

REWRITE record-name [FROM data-name] 

Record-name is the name of a logical record in the File Section of the Data 
Division and may be qualified. Record-name and data-name must refer to 
separate storage areas. 

At the time of execution of this statement, the file to which record-name 
belongs must be open in the I-O mode (see OPEN, Section 4.14). 

If a FROM phrase is included in this statement, the effect is as if MOVE 
data-name TO record-name were executed just prior to the REWRITE. 

Execution of REWRITE replaces the record that was accessed by the most recent 
READ statement; said prior READ must have been completed successfully. If 
the record which is rewriting the record in the file is longer than the file's 
record, only as many bytes as will fit are actually rewritten. On the other hand, 
if the record which is rewriting the record in the file is shorter than the file's 
record, unpredictable information will be written after the record, until the 
beginning of the next record in the file. 
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4.19 GENERAL NOTE ON I/O ERROR HANDLING 

If an I/O error occurs, the file's FILE STATUS item, if one exists, is set to the 
appropriate two-character code, otherwise it assunnes the value "00"* 

If an I/O error occurs and is of the type that is pertinent to an AT END or 
INVALID KEY clause, then the imperative statements in such a clause, if 
present on the statement that gave rise to the error, are executed. But, if there 
is not an appropriate clause (such clauses may not appear on Open or Close, for 
example, and are optional for other I/O statements), then the logic of program 
flow is as follows: 

1. If there is an associated Declaratives ERROR procedure (see Section 
9), it is performed automatically; user-written logic must determine 
what action is taken, because of the existence of the error. Upon 
return from the ERROR procedure, normal program flow to the next 
sentence (following the I/O statement) is allowed. 

2. If no Declaratives ERROR procedure is applicable but there is an 
associated FILE STATUS item, it is presumed that the user may base 
actions upon testing the STATUS item, so normal flow to the next 
sentence isallowed. 

Only if none of the above (INVALID KEY/AT END clause. Declaratives ERROR 
procedure, or testable FILE STATUS item) exists, then the run-time error 
handler receives control; the location of the error (source program line number) 
is displayed on the console, and the run is terminated "abnormally." 

These remarks apply to processing of any file, whether organization is 
sequential, line sequential, indexed or relative. 



4.20 STRING STATEMENT 

The STRING statement allows concatenation of multiple sending data item 
values into a single receiving item. The general format of this statement is: 



STRING 



I operand- 2 
operand-1... DELIMITED BY 

■ SIZE 



i: 



INTO identifier-1 [WITH POINTER identifier-2] 
[ON OVERFLOW imperative-statement] 
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In this format, the term operand means a non-numeric literal, one-character 
figurative constant, or data-name. Identifier-l is the receiving data-item name, 
which must be alphanumeric without editing symbols or the JUSTIFIED clause. 
Identifier-2 is a counter and must be an elementary numeric integer data item of 
sufficient size (plus 1) to point to character positions within identifier-L 

If no POINTER phrase exists, the default value of the logical pointer is one. The 
logical pointer value designates the beginning position of the receiving field into 
which data placement begins. During movement to the receiving field, the 
criteria for termination of an individual source are controlled by the 
"DELIMITED BY" phrase: 

DELIMITED BY SIZE: the entire source field is moved (unless the 
receiving field becomes full) 

DELIMITED BY operand-2: the character string specified by operand-2 is a 
search pattern which, if found to match a contiguous sequence of sending 
characters, terminates the function for the current sending operand (and 
causes automatic switching to the next sending operand, if any). The 
matching characters in the sending fields are not moved to identifier-l. 

If at any point the logical pointer (which is automatically incremented by one for 
each character stored into identifier-l) is less than one or greater than the size 
of identifier-l, no further data movement occurs, and the imperative statement 
given in the OVERFLOW phrase (if any) is executed. If there is no OVERFLOW 
phrase, control is transferred to the next executable statement. 

There is no automatic space fill into any position of identifier-l. That is, 
unaccessed positions are unchanged upon completion of the STRING statement. 

Upon completion of the STRING statement, if there was a POINTER phrase, the 
resultant value of identifier-2 equals its original value plus the number of 
characters moved during execution of the STRING statement. 



4.21 UNSTRING STATEMENT 

The UNSTRING statement causes data in a single sending field to be separated 
into subfields that are placed into multiple receiving fields. The general format 
of the statement is: 

UNSTRING identifier-l 

[ DELIMITED BY [ ALL ] operand-l [OR [ ALL ] operand-2] ...] 

INTO {identifier.2 [ DELIMITER IN identifier-3] 

[ COUNT IN identifier -4]} ... 

[WITH POINTER identifier.5] 

[ TALLYING IN identifier-6] 

[ON OVERFLOW imperative-statement] 
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Criteria for separation of subfields may be given in the "DELIMITED BY" 
phrase. Each time a succession of characters matches one of the non-numeric 
literals, one-character figurative constants, or data-item values named by 
operand-i, the current collection of sending characters is terminated and moved 
to the next receiving field specified by the INTO-clause. When the ALL phrase is 
specified, more than one contiguous occurrence of operand-i in identifier-1 is 
treated as one occurrence. The delimiting string is not moved into the current 
receiving field. 

When two or more delimiters exist, an *0R' condition exists. Each delimiter is 
compared to the sending field in the order specified in the UNSTRING statement. 

Identifier-1 must be a group or character string (alphanumeric) item. When a 
data-item is employed as any operand-i, that operand must also be a group or 
character string item. 

Receiving fields (identifier-2) may be any of the following types of items: 

1. an unedited alphabetic item 

2. a character-string (alphanumeric) item 

3, a group item 

4, an external decimal item (numeric, usage DISPLAY) whose PICTURE 
does not contain any P character. 

When any examination encounters two contiguous delimiters, the current 
receiving area is either space or zero filled depending on its type. If there is a 
"DELIMITED BY" phrase in the UNSTRING statement, then there may be 
"DELIMITER IN" phrases following any receiving item (identifier-2) mentioned in 
the INTO clause. In this case, the character(s) that delimit the data moved Into 
identifier-2 are themselves stored in identifier-3, which should be an 
alphanumeric item. Furthermore, if a "COUNT IN" phrase is present, the 
number of characters that were moved into identifier-2 is moved to identifier-4, 
which must be an elementary numeric integer item. 

If there is a "POINTER" phrase, then identifier-5 must be an integer numeric 
item, and its initial value becomes the initial logical pointer value (otherwise, a 
logical pointer value of one is assumed). The examination of source characters 
begins at the position in identifier-1 specified by the logical pointer; upon 
completion of the UNSTRING statement, the final logical pointer value will be 
copied back into identifier-5. 

If at any time the value of the logical pointer is less than one or exceeds the size 
of identifier-1, then overflow is said to occur and control passes over to the 
imperative statements given in the "ON OVERFLOW" clause, if any. 
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Overflow also occurs when all receiving fields have been filled prior to 
exhausting the source field. 

During the course of source field scanning (looking for matching delimiter 
sequences), a variable length character string is developed which, when 
completed by recognition of a delimiter or by acquiring as many characters as 
the size of the current receiving field can hold, is then moved to the current 
receiving field in the standard MOVE fashion. 

If there is a "TALLYING IN" phrase, identifier-6 must be an integer numeric 
item. The number of receiving fields acted upon, plus the initial value of 
identifier-6, will be produced in identifier-6 upon completion of the UNSTRING 
statement. 

Any subscripting or indexing associated with identif er-l, 5, or 6 is evaluated only 
once at the beginning of the UNSTRING statement. Any subscripting associated 
wth operands-i or identifier-2, 3, 4 is evaluated immediately before access to the 
data item. 



4.22 DYNAMIC DEBUGGING STATEMENTS 

The execution TRACE mode may be set or reset dynamically. When set, 
procedure -names are printed on the user's console in the order in which they are 
executed. 

Execution of the READY TRACE statements sets the trace mode to cause 
printing of every section and paragraph name each time it is entered. The RESET 
TRACE statement inhibits such printing. A printed list of procedure-names in 
the order of their execution is invaluable in detection of a program malfunction; 
it aids in determination of the point at which actual program flow departed from 
the expected program flow. 

Another debugging feature may be required in order to reveal critical data 
values at specifically designated points in the procedure. The EXHIBIT 
statement provides this facility. 



The statement form 



EXHIBIT NAMED ^Eposition-spec] 



identifer 

literal 

ERASE 



...[UPON mnemonic-name] 



produces a printout of values of the indicated literal, or data items in the format 
data-name = value, position-spec and the UPON phrase have the same effect as 
in the DISPLAY statement. 
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Statements EXHIBIT, READY TRACE and RESET TRACE are extensions to 
ANS-74 standard COBOL designed to provide a convenient aid to program 
debugging. 

Programming Note: It is often desirable to include such statements on source 
lines that contain D in column 7, so that they are ignored by the compiler unless 
WITH DEBUGGING MODE is included in the SOURCE-COMPUTER paragraph. 
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CHAPTER 5 
Inter-Program Communication 



Separately compiled COBOL program modules may be combined into a single 
executable program. Inter-program communication is made possible through the 
use of the Linkage Section of the Data Division (which follows the 
Working-Storage Section) and by the CALL statement and the USING list 
appendage to the Procedure Division header of a subprogram module* The 
Linkage Section describes data made available in memory from another program 
module. Record description entries in the LINKAGE section provide data-names 
by which data areas reserved in memory by other programs may be referenced. 
Entries in the LINKAGE section do not reserve memory areas because the data is 
assumed to be present elsewhere in memory, in a CALLing program. 

Any record description clause may be used to describe items in the Linkage 
Section as long as the VALUE clause is not specified for other than level 88 
items. 

The program CHAINing facility allows a COBOL program to transfer control to 
any other executable program and, optionally, to pass data items as parameters 
to the CHAINed program. 



5.1 CALL STATEMENT 

The CALL statement format is 

CALL literal [ USING data-name ... ] 

Literal is a subprogram name defined as the PROGRAM-ID of a separately 
compiled program, and is non-numeric. Data names in the USING list are made 
available to the called subprogram by passing addresses to the subprogram; these 
addresses are assigned to the Linkage Section items declared in the USING list of 
that subprogram. Therefore the number of data-names specified in matching 
CALL and Procedure Division USING lists must be identical. Information passing 
conventions at the machine language level are described in the COBOL-80 User's 
Guide. 



NOTE 

Correspondence between caller and 
callee lists is by position, not by 
identical spelling of names. 
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5-2 EXIT PROGRAM STATEMENT 

The EXIT PROGRAM statement, appearing in a called subprogram, causes 
control to be returned to the next executable statement after CALL in the 
calling program. This statement must be a paragraph by itself. 



5,3 CHAIN STATEMENT 

The CHAIN statement is coded according to the following format: 

literal 
CHAIN { J [USING identifier-2...] 

identifier-l] 

Literal and identifier-1 must be alphanumeric, and identifier-1 must contain a 
terminating space. Each occurrence of identifier-2 must be defined in the 
WORKING- STORAGE or LINKAGE SECTION or in the record area of a file open 
at the time the CHAIN statement is executed. 

When the CHAIN statement is executed, the value of literal or identifier-1, up to 
but not including the first space encountered (or the end of the literal), is 
interpreted as the name of an executable program file in the format of the 
appropriate operating system. The named program is loaded into memory and 
executed. All program and data structures of the CHAINing program are 
permanently destroyed except that the USING clause may be used to transfer 
parameters to the CHAINed program. See section 5.4 (PRODECURE DIVISION 
Header with CALL and CHAIN). 

The CHAINed program need not be a COBOL program. If it is, it must be a main 
program. 
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5.4 PROCEDURE DIVISION HEADER WITH CALL AND CHAIN 
The PROCEDURE DIVISION header of a main program is written as: 

PROCEDURE DIVISION [ CHAINING data-name-L-.]. 
The PROCEDURE DIVISION header of a subprogram is written as: 

PROCEDURE DIVISION USING [data-name- 2...]. 



The various forms of the PROCEDURE DIVISION header describe the linkage 
and parameter initialization requirements of a program. A main program must 
be linked by itself or with any number of subprograms. It may then be run 
independently or invoked by the execution of a CHAIN statement in another 
program. A subprogram must be linked with exactly one main program and, 
optionally, any number of other subprograms. It may only be executed by the 
action of a CALL statement. For a description of the linking process, see the 
COBOL-80 User's Guide- 

A CHAINed or CALLed program should have a CHAINing list or non-empty 
USING list if and only if the invoking CHAIN or CALL statement has a USING 
list. Furthermore, the numbers of entries in the lists should be equal, and 
positionally corresponding entries in the two lists should reference data items of 
the same size and USAGE. Failure to conform to these rules will not be 
diagnosed and will cause unpredictable results at runtime. 

The values of the data items named in the PROCEDURE DIVISION header are 
established at program initialization time by using the contents of positionally 
corresponding data items named in the invoking CALL or CHAIN statement. In 
the case of CALL, the identification is made by passing pointers. Therefore, if 
the value of a data item named in a PROCEDURE DIVISION USING clause is 
changed during subprogram execution, the corresponding data item in the 
CALLing program will reflect the change after control is returned from the 
subprogram. 

For a description of the formats in which parameters are passed by the CALL 
and CHAIN statements, see the COBOL-80 User's Guide. 
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CHAPTER 6 
Table Handling by the Indexing Method 



In addition to the capabilities of subscripting described in Chapter 3, COBOL 
provides the indexing method of table handling. 



6.1 INDEX NAMES AND INDEX ITEMS 

^^ 't^dex name is declared not by the usual method of level number, name, and 
data description clauses, but implicitly by appearance in the "INDEXED BY 
index-name" appendage to an OCCURS clause. An index-name must be unique. 

An index data item is an item defined by the USAGE IS INDEX phrase. An index 
data item must not have a PICTURE. An index name or index data item may 
only be referred to by a SET or SEARCH statement, a CALL statement's USING 
list or a Procedure header USING list; or used in a relation condition or as the 
variation item in a PERFORM VARYING statement, or in place of a subscript. 
In all cases the process is equivalent to dealing with a binary word integer 
subscript. Index-name must be initialized to some value before use via SET, 
SEARCH or PERFORM. 



6.2 SET STATEMENT 

The SET statement permits the manipulation of index-names, index items, or 
binary subscripts for table-handling purposes. There are two formats. 



Format 1: 



SET 



Format 2: 



SET 



index-name-l] 

index-item-1 

data-name-1 



index-name-3 



TO 



f index-name- 21 
index-item-2 
data-name-2 

Jnteger-2 



(UBSY ] (data-name-4 
I DOWN BY I [integer-4 



Format 1 is equivalent to moving the "TO" value (e.g., integer-2) to multiple 
receiving fields written immediately after the verb SET. 
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Format 2 is equivalent to reduction (DOWN) or increase (UP) applied to each of 
the quantities written immediately after the verb SET: the amount of the 
reduction or increase is specified by a name or value immediately following the 
word BY. 

In any SET statement, data-names are restricted to integer items. 



6.3 RELATIVE INDEXING 

A user reference to an item in a table controlled by an OCCURS clause is 
expressed with a proper number of subscripts (or indices), separated by commas. 
The whole is enclosed in matching parentheses, for example: 

TAX-RATE (BRACKET, DEPENDENTS) 
XCODE (I, 2) 

where subscripts are ordinary integer decimal data-names, or integer constants, 
or binary integer (COMPUTATIONAL or INDEX) items, or index-names. 
Subscripts may be qualified, but not, themselves, subscripted. A subscript may 
be signed, but if so, it must be positive. The lowest acceptable value is 1, 
pointing to the first element of a table. The highest permissible value is the 
maximum number of occurrences of the item as specified in its OCCURS clause. 

A further capability exists, called relative indexing. In this case, a "subscript" is 
expressed as 

name + integer constant 

where a space must be on either side of the plus or minus, and "name" may be 
any proper index-name. 

Example: 

XCODE (1 + 3, J - 1). 
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6.4 SEARCH STATEMENT - Format 1 

A linear search of a table may be done using the SEARCH statement. The 
general format is: 

SEARCH table [ VARYING identifier I index-name] 

[AT END imperative-statement-1] 

(when Condition-l [ nEXT SENTENCE jl 

I imperati ve-statement-2 j j ..• 



V 



Table is the name of a data-item having an OCCURS clause that includes an 
INDEXED BY list; table must be written without subscripts or indexes because 
the nature of the SEARCH statement causes automatic variation of an 
index-name associated with a particular table. 

There are four possible VARYING cases: 

1. NO VARYING phrase — the first-listed index-name for the table is 
varied. 

2. VARYING index-name-in-a-different-table — the first-listed 
index-name in the table's definition is varied, implicitly, and the 
index-name listed in the VARYING phrase is varied in like manner, 
simultaneously, 

3. VARYING index-name-defined-for-table — this specific index-name is 
the only one varied. 

4. VARYING integer-data-item-name — both this data-Item and the 
first-listed index-name for table are varied, simultaneously. 

The term variation has the following interpretation: 

1. The initial value is assumed to have been established by an earlier 
statement such as SET. 

2. If the initial value exceeds the maximum declared in the applicable 
OCCURS clause, the SEARCH operation terminates at once; and if an 
AT END phrase exists, the associated imperative statement-1 is 
executed. 

3. If the value of the index is within the range of valid indexes (1,2,... 
up to and including the maximum number of occurrences), then each 
WHEN-condition is evaluated until one is true or all are found to be 
false. If one is true, its associated imperative statement is executed 
and the SEARCH operation terminates. If none is true, the index is 
incremented by one and step (3) is repeated. Note that incrementation 
of index applies to whatever item and/or index is selected according to 
rules 1-4. 
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If the table is subordinate to another table, an index-name must be associated 
with each dimension of the entire table via INDEXED BY phrases in all the 
OCCURS clauses* Only the index-name of the SEARCH table is varied (along 
with another VARYING index-name or data-item). To search an entire two- or 
three-dimensional table, a SEARCH must be executed several times with the 
other index-names set appropriately each time, probably with a PERFORM, 
VARYING statement* 

The logic of a Format 1 SEARCH is depicted on page 84. 



6.5 SEARCH STATEMENT - Format 2 

I ■ "" ■ ' ■ "" ■ ■' ■ 

Format 2 SEARCH statements deal with tables of ordered data. The general 
format of such a SEARCH ALL statement is: 

SEARCH ALL table [AT END imperative-statement-L..] 

WHEN condition fimperative-statement-2... 

[ NEXT SENTENCE 

Only one WHEN clause is permitted, and the following rules apply to the 
condition: 

1. Only simple relational conditions or condition-names may be 
employed, and the subject must be properly indexed by the first 
index-name associated with table (along with sufficient other indexes 
if multiple OCCURS clauses apply). Furthermore, each subject 
data-name (or the data-name associated with condition-name) in the 
condition must be mentioned in the KEY clause of the table. The KEY 
clause is an appendage to the OCCURS clause having the following 
format: 

ASCENDING I DESCENDING KEY IS data-name ... 

where data-name It the name defined in this Data Description entry 
(following level number) or one of the subordinate data-names. If 
more than one data-name is given, then all of them must be the names 
of entries subordinate to this group item. The KEY phrase indicates 
that the repeated data is arranged in ascending or descending order 
according to the data-names which are listed (in any given KEY 
phrase) in decreasing order of significance. More than one KEY phrase 
may be specified. 

2. In a simple relational condition, only the equality test (using relation = 
or IS EQUAL TO) is permitted. 
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3. Any condition-name variable (Level 88 items) must be defined as 
having only a single value. 

4. The condition may be compounded by use of the Logical connector 
AND, but not OR. 

5. In a simple relational condition, the object (to the right of the equal 
sign) may be a literal or an identifier; the identifier must NOT be 
referenced in the KEY clause of the table or be indexed by the first 
index-name associated with the table. (The term identifier means 
data-name, including any qualifiers and/or subscripts or indexes.) 

Failure to conform to these restrictions may yield unpredictable results. 
Unpredictable results also occur if the table data is not ordered in conformance 
to the declared KEY clauses, or if the keys referenced in the WHEN-condition 
are not sufficient to identify a unique table element. 

In a Format 2 SEARCH, a nonserial type of search operation may take place, 
relying upon the declared ordering of data. The initial setting of the index-name 
for table is ignored and its setting is varied automatically during the searching, 
always within the bounds of the maximum number of occurrences. If the 
condition (WHEN) cannot be satisfied for any valid index value, control is passed 
to imperative-statement-1, if the AT END clause is present, or to the next 
executable sentence in the case of no AT END clause. 

If aU^ the simple conditions in the single WHEN-condition are satisfied, the 
resultant index value indicates an occurrence that allows those conditions to be 
satisfied, and control passes to imperative-statement-2. Otherwise the final 
setting is not predictable. 
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Logic Diagram for Format 1 SEARCH 
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CHAPTER 7 
Indexed Files 

7.1 DEFINITION OF INDEXED FILE ORGANIZATION 

An indexed-file organization provides for recording and accessing records of a 
data file by keeping a directory (called the control index ) of pointers that enable 
direct location of records having particular unique key values. An indexed file 
must be assigned to DISK in its defining SELECT sentence, 

A file whose organization is indexed can be accessed either sequentially, 
dynamically or randomly. 

Sequential access provides access to data records in ascending order of RECORD 
KEY values. 

In the random access mode, the order of access to records is controlled by the 
programmer. Each record desired is accessed by placing the value of its key in a 
key data item prior to an access statement. 

In the dynamic access mode, the programmer's logic may change from sequential 
access to random access, and vice versa , at will. 

7.2 SYNTAX CONSIDERATIONS 

In the Environment Division, the SELECT entry must specify ORGANIZATION IS 
INDEXED, and the ACCESS clause format is 

ACCESS MODE IS SEQUENTIAL I RANDOM I DYNAMIC . 

Assign, Reserve, and File Status clause formats are identical to those specified 
in Section 2.2.1 of this manual. 

In the FD entry for an INDEXED file, both LABEL RECORDS STANDARD and a 
VALUE OF FILE-ID clause must appear. The formats of Section 3.13 apply, 
except that only the DISK-related forms are applicable. 
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7.2.1 RECORD KEY CLAUSE 

The general fornnat of this clause, which is required, is: 

RECORD KEY IS data-name-l 

where data-name-l is an item defined within the record descriptions of the 
associated file description, and is a group item or an elementary alphanumeric 
item. The maximum key length is 60 bytes and the key should never be made to 
contain all nulls. 

If random access mode is specified, the value of data-name-1 designates the 
record to be accessed by the next DELETE, READ, REWRITE or WRITE 
statement. Each record must have a unique record key value. 

7-2.2 FILE STATUS REPORTING 

If a FILE STATUS clause appears in the Environment Division for an Indexed 
organization file, the designated two-character data item is set after every I-O 
statement. The following table summarizes the possible settings. 



Status Data 
Item LEFT 
Character 


Status Data Item RIGHT Character 


No Further 
Description 
(0) 


Structure 
Error 
. (1) 


Duplicate 

Key 

(2) 


No Record 
Found 

(3) 


Disk Space 

Full 

(4) 


Successful 
Completion (0) 


X 










At End (1) 


X 










Invalid 
Key (2) 




X 


X 


X 


X 


Permanent 
Error(3) 


X 








X 


Special 
Cases (9) 




X 









File Status '21* arises if ACCESS MODE is SEQUENTIAL when WRITEs do not 
occur in ascending sequence for an indexed file, or the key is altered prior to 
REWRITE. In an OPEN INPUT or OPEN I-O statement, a File Status of '30' 
means 'File Not Found.' File Status '91» occurs on an OPEN INPUT or OPEN I-O 
statement for a relative or indexed file whose structure has been destroyed (for 
example, by a system crash during output to the file). When this status is 
returned on an OPEN INPUT, the file is considered to be open, and READs may 
be executed. On an OPEN I-O, however, the file is not considered to be open, 
and all I/O operations fail. The other settings are self-explanatory. 

Note that "Disk Space Full" occurs with Invalid Key (2) for indexed and relative 
file handling, whereas it occurred with "Permanent Error" (3) for sequential files. 
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If an error occurs at execution time and no AT END or INVALID KEY 
statennents are given and no appropriate Declarative ERROR section is supplied 
and no FILE STATUS is specified, the error will be displayed on the console and 
the program will terminate. See Section 4,19, 



7.3 PROCEDURE DIVISION STATEMENTS FOR INDEXED RLES 

The syntax of the sequential file OPEN statement (Section 4.14) also applies to 
indexed organization files, except that EXTEND is not applicable. 

The following table summarizes the available statement types and their 
permissibility in terms of ACCESS mode and OPEN option in effect. Where X 
appears, the statement is permissible, otherwise it is not valid under the 
associated- ACCESS mode and OPEN option. 



ACCESS 
MODE IS 


Procedure 
Statement 


OPEN 


Option in Effect 




Input 


Output 


I-O 




READ 


X 




X 




WRITE 




X 




SEQUENTIAL 


REWRITE 






X 




START 


X 




X 




DELETE 






X 




READ 


X 




X 




WRITE 




X 


X 


RANDOM 


REWRITE 

START 

DELETE 






X 
X 




READ 


X 




X 




WRITE 




X 


X 


DYNAMIC 


REWRITE 






X 




START 


X 




X 




DELETE 






X 



In addition to the above statements, CLOSE is permissible under all conditions; 
the same format shown in Section 4.17 is used. 
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lA READ STATEMENT 

Format 1 (Sequential Access): 

READ file-name [ NEXT ] RECORD [INTO data-name-l] 

[AT END imperative-statement .*.] 

Format 2 (Random or Dynamic Access): 

READ file-name RECORD [INTO data-name-1] [ KEY IS data-name-2] 

[INVALID KEY imperative-statement,..] 

Format 1 without NEXT must be used for ail files having SEQUENTIAL ACCESS 
mode. Format 1 with the NEXT option is used for sequential READs of a 
DYNAMIC access mode file. The AT END clause is executed when the logical 
end-of-file condition arises. If this clause is not written in the source statement, 
an appropriately assigned Declaratives ERROR section is given control at 
end-of-file time, if available. 

Format 2 is used for files in random-access mode or for files in dynamic-access 
mode when records are to be retrieved randomly. 

In format 2, the INVALID KEY clause specifies action to be taken if the access 
key value does not refer to an existing key in the file. If the clause is not given, 
the appropriate Declaratives ERROR section, if supplied, is given control. 

The optional KEY IS clause must designate the record key item declared in the 
file's SELECT entry. This clause serves as documentation only. The user must 
ensure that a valid key value is in the designated key field prior to execution of a 
random -access READ. 

The rules for sequential files regarding the INTO phrase apply here as well. 
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7.5 WRITE STATEMENT 

The WRITE statement releases a logical record for an output or input-output file; 
its general format is: 

WRITE record-name [ FROM data-name-1] 

[INVALID KEY imperative-statement.,-] 

Just prior to executing the WRITE statement, a valid (unique) value must be in 
that portion of the record-name (or data-name-1 if FROM appears in the 
statement) which serves as RECORD KEY. 

In the event of an improper key value, the imperative statements are executed if 
the INVALID KEY clause appears in the statement; otherwise an appropriate 
Declaratives ERROR section is invoked, if applicable. The INVALID KEY 
condition arises if: 

1. for sequential access, key values are not ascending from one WRITE to 
the next WRITE; 

2. the key value is not unique; 

3. the allocated disk space is exceeded. 



7.6 REWRITE STATEMENT 

The REWRITE statement logically replaces an existing record; the format of the 
statement is: 

REWRITE record-name [ FROM data-name] 
[INVALID KEY imperative-statement...] 

For a file in sequential-access mode, the last READ statement must have been 
successful in order for a REWRITE statement to be valid. If the value of the 
record key in record-name (or corresponding part of data-name, if FROM 
appears in the statement) does not equal the key value of the immediately 
previous READ, then the invalid key condition exists and the imperative 
statements are executed, if present; otherwise an applicable Declaratives 
ERROR section is executed, if available. 

For a file in a random or dynamic access mode, the record to be replaced is 
specified by the record key; no previous READ is necessary. The INVALID KEY 
condition exists when the record key's value does not equal that of any record 
stored in the file. 
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IJ DELETE STATEMENT 

The DELETE statement logically rennoves a record from an indexed file* The 
general format of the statement is: 

DELETE file-name RECORD [INVALID KEY imperative-statement*..] 

For a file in the sequential access mode, the last input-output statement 
executed for file-name must have been a successful READ statement. The 
record that was read is deleted. Consequently, no INVALID KEY phrase should 
be specified for sequential-access mode files. 

For a file having random or dynamic access mode, the record deleted is the one 
associated with the record key; if there is no such matching record, the invalid 
key condition exists, and control passes to the imperative statements in the 
INVALID KEY clause, or to an applicable Declarative ERROR section if no 
INVALID KEY clause exists. 



7.8 START STATEMENT 

The START statement enables an indexed organization file to be positioned for 
reading at a specified key value. This is permitted for files open in either 
sequential or dynamic access modes. The format of this statement is: 



START file-name 



[ GREATER THAN] 
KEY IS i NOT LESS THAN \ data-name 
( EQUAl TD j 



[INVALID KEY imperative statement...] 

Data-name must be the declared record key and the value to be matched by a 
record in the file must be pre-stored in the data-name. When executing this 
statement, the file must be open in the input or I-O mode. 

If the KEY phrase is not present, equality between a record in the file and the 
record key value is sought. If key relation GREATER or NOT LESS is specified, 
the file is positioned for next access at the first record greater than, or greater 
than or equal to, the indicated key value. 

If no matching record is found, the imperative statements in the INVALID KEY 
clause are executed, or an appropriate Declaratives ERROR section is executed. 
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Relative Files 

8.1 DEFINITION OF RELATIVE FILE ORGANIZATION 

Relative organization is restricted to disk files. Records are differentiated on 
the basis of a relative record number which ranges from 1 to 32,767, or to a 
lesser maximum for a smaller file. Unlike the case of an indexed file, where the 
identifying key field occupies a part of the data record, relative record numbers 
are conceptual and are not embedded in the data records. 

A relative organization file may be accessed either sequentially, dynamically or 
randomly. In sequential access mode, records are accessed in the order of 
ascending record numbers. 

In random access mode, the sequence of record access is controlled by the 
program, by placing a number in a relative key item. In dynamic access mode, 
the program may inter-mix random and sequential access at will. 

8.2 SYNTAX CONSIDERATIONS 

Tn the Environment Division, the SELECT entry must specify ORGANIZATION IS 
RELATIVE , and the ACCESS clause format is 

ACCESS MODE IS SEQUENTIAL I RANDOM I DYNAMIC . 

Assign, Reserve, and File Status clause formats are identical to those used for 
sequential or indexed organization files. The values of STATUS Key 2 when 
STATUS Key 1 equals 'T are: 

'2' for attempt to WRITE a duplicate key 

'3' for nonexistent record 

^4' for disk space full 

In the associated FD entry, STANDARD labels must be declared and a VALUE 
OF FILE-ID clause must be included. 

Thie first byte of the record area associated with a relative file should not be 
described as part of a COMP or COMP-3 item by any record description for the 
file. 
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8,2.1 RELATIVE KEY CLAUSE 

In addition to the usual clauses in the SELECT entry, a clause of the form 

RELATIVE KEY IS data-name-l 

is required for random or dynamic access mode. It is also required for 
sequential-access mode, if a START statement exists for such a file, 

Data-name-1 must be described as an unsigned binary integer item not contained 
within any record description of the file itself* Its value must be positive and 
nonzero. 



8.3 PROCEDURE DIVISION STATEMENTS FOR RELATIVE RLES 

Within the Procedure Division, the verbs OPEN, CLOSE, READ, WRITE, 
REWRITE, DELETE and START are available, just as for files whose organization 
is indexed. (Therefore the charts in Sections 7.2.2 and 7.3 also apply to 
RELATIVE files.) The statement formats for sequential file OPEN and CLOSE 
(see Sections 4.14 and 4.17) are applicable to relative files, except for the 
"EXTEND" phrase. 



8.4 READ STATEMENT 

Format 1: 

READ file-name [NEXT] RECORD [INTO data-name] 



[AT END imperative statement...] 



Format 2: 

READ file-name RECORD [INTO data-name] 

[INVALID KEY imperative statement...] 

Format 1 must be used for all files in sequential access mode. The NEXT phrase 
must be present to achieve sequential access if the file's declared mode of 
access is Dynamic. The AT END clause, if given, is executed when the logical 
end-of-file condition exists, or, if not given, the appropriate Declaratives 
ERROR section is given control, if available. 

Format 2 is used to achieve random access with declared mode of access either 
Random or Dynamic. 
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If a Relative Key is defined (in the file's SELECT entry), successful execution of 
a fornnat 1 READ statement updates the contents of the RELATIVE KEY itenn 
("data-name- 1") so as to contain the record number of the record retrieved. 

For a format 2 READ, the record that is retrieved is the one whose relative 
record number is pre-stored in the RELATIVE KEY item. If no such record 
exists, however, the INVALID KEY condition arises, and is handled by (a) the 
imperative statements given in the INVALID KEY portion of the READ, or (b) an 
associated Declaratives section. 

The rules for sequential files regarding the INTO phrase apply here as well. 



8.5 WRITE STATEMENT 

The format of the WRITE statement is the same for a relative file as for an 
indexed file: 

WRITE record-name [ FROM data-name] 

[INVALID imperative statement...] 

If access mode is sequential, then completion of a WRITE statement causes the 
relative record number of the record just output to be placed in the RELATIVE 
KEY item. 

If access mode is random or dynamic, then the user must pre-set the value of the 
RELATIVE KEY item in order to assign the record an ordinal (relative) number. 
The INVALID KEY condition arises if there already exists a record having the 
specified ordinal number, or if the disk space is exceeded. 



8.6 REWRITE STATEMENT 

The format of the REWRITE statement is the same for a relative file as for an 
indexed file: 

REWRITE record-name [ FROM data-name] 

[INVALID KEY imperative statement ...] 

For a file in sequential access mode, the immediately previous action must have 
been a successful READ; the record thus previously made available is replaced in 
the file by executing REWRITE. If the previous READ was unsuccessful, a 
run-time error will terminate execution. Therefore, no INVALID KEY clause is 
allowed for sequential access. 
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For a file with dynamic or random access mode declared, the record that is 
replaced by executing REWRITE is the one whose ordinal number is pre-set in the 
RELATIVE KEY item. If no such item exists, the INVALID KEY condition 
arises. 



3.7 DELETE STATEMENT 

The format of the DELETE statement is the same for a relative file as for an 
indexed file: 

DELETE file-name RECORD 

[INVALID KEY imperative statement...] 

For a file in a sequential access mode, the immediately previous action must 
have been a successful READ statement; the record thus previously made 
available is logically removed from the file. If the previous READ was 
unsuccessful, a run-time error will terminate execution. Therefore, an INVALID 
KEY phrase may not be specified for sequential -access mode files. 

For a file with dynamic or random access mode declared, the removal action 
pertains to whatever record is designated by the value in the RELATIVE KEY 
item. If no such numbered record exists, the INVALID KEY condition arises. 



8.8 START STATEMENT 



The format of the START statement is the same for a relative file as for an 
indexed file: 



START file-name 



KEY IS 



( GREATER THAN) 
NOT LESS THAN 
EQUALTO 



data-name-1 



[INVALID KEY imperative statement...] 

Execution of this statement specifies the beginning position for reading 
operations; it is permissible only for a file whose access mode is defined as 
sequential or dynamic- 

Data-name may only be that of the previously declared RELATIVE KEY item, 
and the number of the relative record must be stored in it before START is 
executed. When executing this statement, the associated file must be currently 
open in INPUT or I-O mode. 
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If the KEY phrase is not present, equality between a record in the file and the 
record key value is sought. If key relation GREATER or NOT LESS is specified, 
the file is positioned for next access at the first record greater than, or greater 
than or equal to, the indicated key value. 

If no such relative record is found, the imperative statements in the INVALID 
KEY clause are executed, or an appropriate Declaratives ERROR section is 
executed. 
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The Declaratives region provides a method of including procedures that are 
executed not as part of the sequential coding written by the programmer, but 
rather when a condition that cannot normally be tested by the programmer 
occurs. 

Although the system automatically handles checking and creation of standard 
labels and executes error recovery routines in the case of input/output errors, 
additional procedures may be specified by the COBOL programmer. 

Since these procedures are executed only at the time an error in reading or 
writing occurs, they cannot appear in the regular sequence of procedural 
statements. They must be written at the beginning of the Procedure Division in 
a subdivision called DECLARATIVES. Related procedures are preceded by a 
USE sentence that specifies their function. A declarative section ends with the 
occurrence of another section-name with a USE sentence or with the key words 
END DECLARATIVES. 

The key words DECLARATIVES and END DECLARATIVES must each begin in 
Area A and be followed by a period. 

PROCEDURE DIVISION . 

DECLARATIVES . 

(section-name SECTION . USE sentence. 

(paragraph-name, (sentence}...} •..} ... 

END DECLARATIVES . 

The USE sentence defines the applicability of the associated section of coding. 
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A USE sentence, when present, must immediately follow a section header in the 
Declarative portion of the Procedure Division and must be followed by a period 
followed by a space. The remainder of the section must consist of zero, one or 
more procedural paragraphs that define the procedures to be used. The USE 
sentence itself is never executed; rather, it defines the conditions for the 
execution of the USE procedure. The general format of the USE sentence is 

USE AFTER STANDARD EXCEPTION I ERROR PROCEDURE 

ON (file-name... I INPUT i OUTPUT I UO I EXTEND}. 

The words EXCEPTION and ERROR may be used interchangeably. The 
associated declarative section is executed (by the PERFORM mechanism) after 
the standard I-O recovery procedures for the files designated, or after the 
INVALX) KEY or AT END condition arises on a statement lacking the INVALID 
KEY or AT END clause. A given file-name may not be associated with more 
than one declarative section. 

Within a declarative section there must be no reference to any nondeclarative 
procedure. Conversely, in the nondeclarative portion there must be no reference 
to procedure-names that appear in the declaratives section, except that 
PERFORM statements may refer to a USE statement and its procedures; but in a 
range specification (see PERFORM, Section 4.10) if one procedure -name is in a 
Declarative Section, then the other must be in the same Declarative Section. 

An exit from a Declarative Section is inserted by the compiler following the last 
statement in the section. All logical program paths within the section must lead 
to the exit point. 
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The program segmentation facility is provided to enable the execution of 
COBOL-80 programs which are larger than physical memory. When segmentation 
is used (that is, when any section header in the program contains a segment 
number) the entire PROCEDURE DIVISION must be written in sections. Each 
section is assigned a segment number by a section header of the form: 

section-name SECTION [segment-number]. 

segment-number must be an integer with a value in the range from through 99. 
If segment-number is omitted, it is assumed to be 0. Declaratives sections must 
have segment -numbers less than 50. All sections which have the same segment 
number constitute a single program segment and must occur together in the 
source program. Furthermore, all segments with numbers less than 50 must 
occur together at the beginning of the PROCEDURE DIVISION. 

Segments with numbers through 49 are called fixed segments and are aways 
resident in memory during execution. Segments with numbers greater than 49 
are called independent segments. Each independent segment is treated as a 
program overlay. An independent segment is in its initial state when control is 
passed to it for the first time during the execution of a program, and also when 
control is passed to that section (implicitly or explicitly) from another segment 
with a different segment number. Specifically, an independent segment is in its 
initial state when it is reached by "falling through" the end of a fixed or 
different independent segment. 

Segmentation causes the following restrictions on the use of the ALTER and 
PERFORM statements: 

1. A GO TO statement in an independent segment must not be referred 
to by an ALTER statement in any other segment. 

2. A PERFORM statement in a fixed segment may have within its range 
only 

a. sections and/or paragraphs wholly contained within fixed 
segments, or 

b. sections and/or paragraphs wholly contained in a single 
independent segment. 
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3. A PERFORM statement in an independent segment may have within 
its range only 

a, secticns and/or paragraphs wholly contained within fixed 
segments, or 

b, sections and/or paragraphs wholly contained within the same 
independent segment as the PERFORM statement. 
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Evaluation Rules for Compound Conditions 

1. Evaluation of individual simple conditions (relation, class, 
condition-name, and sign test) is done first, 

2. AND-connected simple conditions are evaluated next as a single result. 

3. OR and its adjacent conditions (or previously evaluated results) are 
then evaluated. 

EXAMPLES: 

1. A < B OR C = D OR E NOT > F 

The evaluation is equivalent to (A<B) OR (C=0) OR (E<F) and is true if 
any of the three individual parenthesized simple conditions is true. 

2. WEEKLY AND HOURS NOT = 

The evaluation is equivalent, after expanding level 88 condition-name 
WEEKLY, to 

(PAY -CODE = W) AND (HOURS ;tO) 

and is true only if both the simple conditions are true. 

3. A = 1 AND 8*= Z AND G > -3 
OR P NOT EQUAL TO "SPAIN" 
is evaluated as 

[(A = 1) AND (B = 2) AND (G >.3)] 

OR (P /= "SPAIN") 

If P = "SPAIN", the compound condition can only be true if all three of 
the following are true: 

(c.l) A = 1 
(c.2) B = 2 
(c.3) G > .3 

However, if P is not equal to "SPAIN", the compound condition is true 
regardless of the values of A, B and G. 
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Parenthesized Conditions 

Parentheses may be written within a compound condition or parts thereof in 
order to specify precedence in the evaluation order. 

Example: 

IF A = B AND (A = 5 OR A = 1) 
PERFORM PROCEDURE-44. 

In this case, PROCEDURE-44 is executed ifA=50RA = l while at the same 
time A = B. In this manner, compound conditions may be formed containing 
other compound conditions, not just simple conditions, via the use of parentheses. 



Abbreviated Conditions 

For the sake of brevity, the user may omit the "subject" when it is common to 
several successive relational tests. For example, the condition A = 5 OR A = 1 
may be written A = 5 OR = 1. This may also be written A = 5 OR 1, where both 
subject and relation being implied are the same. 

Another example: 

FA = BOR<CORY 
is a shortened form of 

FA = BORA<CORA<Y 

The interpretation applied to the use of the word ^NOT' in an abbreviated 
condition is: 

1. If the item immediately following 'NOP is a relational operator, then 
the 'NOP participates as part of the relational operator; 

2. otherwise, the beginning of a new, completely separate condition must 
follow 'NOP, not to be considered part of the abbreviated condition. 

Caution: Abbreviations in which the subject and relation are implied are 
permissible only in relation tests; the subject of a sign test or class test cannot 
be omitted. 

NOT, the Logical Negation Operator 

In addition to its use as a part of a relation (e.g., IF A IS NOT = B), "NOT" may 
precede a condition. For example, the condition NOT (A = B OR C) Is true when 
(A = B OR A = C) is false. The word NOT may precede a level 88 condition 
name, also. 
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APPENDIX II 
Table of Permissible MOVE Operands 



Source 
Operand 


Receiving Operand in MOVE Statement 


Numeric 
Integer 


Numeric 
Non-integer 


Numeric 
Edited 


Alphanumeric 
Edited 


Alphanumeric 


Gro 


Numeric Integer 


OK 


OK 


OK 


OK (A) 


OK (A) 


OK 


Numeric Non-integer 


OK 


OK 


OK 






OK 


Numeric Edited 








OK 


OK 


OK 


Alphanumeric Edited 








OK 


OK 


OK 


Alphanumeric 


OK(C) 


OK(C) 


OK (C) 


OK 


OK 


OK 


Group 


OK (B) 


OK(B) 


OK(B) 


OK(B) 


OK (B) 


OK 



KEY: (A) Source sign, if any, is ignored 

(B) If the source operand or the receiving operand is a Group Itenn, 
the move is considered to be a Group Move* See Section 4,3 for a 
discussion of the effect of a Group Move, 

(C) Source is treated as an unsigned integer; source length may not 
exceed 31. 

NOTE: No distinction is made in the compiler between alphabetic and 
alphanumeric; one should not move numeric items to alphabetic items and 
vice versa. 
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APPENDIX III 
Nesting of W Statements 



A "nested IF" exists when the verb . IF appears more than once in a single 
sentence. 

Example: 

IFX = Y 

IF A = 8 

MOVE"*" TO SWITCH 
ELSE 

MOVE "A" TO SWITCH 
ELSE 

MOVE SPACE TO SWITCH 

The flow of the above sentence may be represented by a tree structure: 




Another useful way of viewing nested IF structures is based on numbering IF and 
ELSE verbs to show their priority. 

Fl X =Y 



true 
actionl: 



•• I 



IF2 A = B 

true-action : MOVE"*" TO SWITCH 
ELSE2 false-action2 : MOVE "A" TO SWITCH 



ELSEl 



false-action 1 : MOVE SPACE TO SWITCH. 
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The above illustration shows clearly the fact that IF2 is wholly nested within the 
true-action side of IFl. 

The number of ELSEs in a sentence need not be the same as the number of IFs; 
there may be fewer ELSE branches. 



Examples: 

FM =1 

IFK = 

GO TO Ml-KO 
ELSE 

GO TO Ml-KNOTO. 

F AMOUNT IS NUMERIC 
IF AMOUNT IS ZERO 

GO TO CLOSE-OUT. 

In the latter case, F2 could equally well have been written as AND. 
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APPENDIX IV 

ASCn Character Set 
For ANS-74 COBOL 



aracter 


Octal Value 


Character 


Octal Value 


A 


101 





60 


B 


102 


1 


61 


C 


103 


2 


62 


D 


104 


3 


63 


E 


105 


4 


64 


F 


106 


5 


65 


G 


107 


6 


66 


H 


110 


7 


67 


I 


111 


8 


70 


J 


112 


9 


71 


K 


113 


(SPACE) 


40 


L 


114 


ft 


42 


M 


115 


$ 


44 


N 


116 


' (ncn-ANSI) 


47 





117 


( 


50 


P 


120 


) 


51 


Q 


121 


* 


52 


R 


122 


+ 


53 


S 


123 


f 


54 


T 


124 


- 


55 


U 


125 


, 


56 


V 


126 


/ 


57 


w 


127 


J 


73 


X 


130 


< 


74 


Y 


131 


- 


75 


z 


132 


> 


76 



Plus-zero (zero with embedded positive sign); 173 
Minus-zero (zero with embedded negative sign); 175 
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APPENDIX V 
Reserved Words 



+ indicates additional words required by COBOL-SO for interactive screens, 
Debug extensions, and packed decimal format 



ACCEPT 

ADVANCING 

ALPHABETIC 

ALTERNATE 

AREA(S) 

ASSIGN 

AUTO 

BEFORE 

BLANK 

BOTTOM 

CANCEL 

CH 

CHARACTER(S) 

COBOL 

COL+ 

COLUMN 

COMP 

C0MPUTATI0NAL-3+ 

CONTAINS 

CORR(ESPONDING) 

DATA 

DATE-WRITTEN 

DEBUG-CONTENTS 

DEBUG-NAME 

DEBUG- SU8-3 

DECLARATIVES 

DELIMITER 

DESTINATION 

DISPLAY 

DOWN 

EGI 

ENABLE 

ENTER 

EQUAL 

ESCAPE 

EXCEPTION 

EXTEND 

FILE CONTROL 

FINAL 

FOR 

GENERATE 

GREATER 

HIGH-VALUE(S) 

I-0-CONTROL 

IN 

INITIAL 

INPUT-OUTPUT 

INTO 



ACCESS 

AFTER 

ALSO 

AND 

ASCENDING 

AT 

AUTO-SKIP+ 

BELL 

BLINK 

BY 

CD 

CHAIN 

CLOCK -UNITS 

CODE 

COLLATING 

COMMA 

C0MP-3+ 

COMPUTE 

CONTROL(S) 

COUNT 

DATE 

DAY 

DEBUG-ITEM 

DEBUG-SUB-1 

DEBUGGING 

DELETE 

DEPENDING 

DISABLE 

DIVIDE 

DUPLICATES 

ELSE 

END 

ENVIRONMENT 

ERASE+ 

ESI 

EXHIBIT+ 

FD 

FILE-ID+ 

RRST 

FROM 

GIVING 

GROUP 

HIGHLIGHT 

IDENTinCATION 

INDEX 

INITIATE 

INSPECT 

INVALID 



ADD 

ALL 

ALTER 

ARE 

ASCII+ 

AUTHOR 

BEEP+ 

BLANK 

BLOCK 

CALL 

CF 

CHAINING 

CLOSE 

CODE-SET 

COLUMN 

COMMUNICATION 

COMPUTATIONAL 

CONFIGURATION 

COPY 

CURRENCY 

DATE-COMPILED 

DE(TAIL) 

DEBUG-LINE 

DEBUG-SUB-2 

DECIMAL-POINT 

DELIMITED 

DESCENDING 

DISK+ 

DIVISION 

DYNAMIC 

EMI 

END-OF-PAGE 

EOP 

ERROR 

EVERY 

EXIT 

RLE 

FILLER 

FOOTING 

FROM 

GO 

HEADING 

I-O 

IF 

INDEXED 

INPUT 

INSTALLATION 

IS 
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JUSTdnKD) 


KEY 


LABEL 


LAST 


1 FADING 


LEFT 


LEFT-JUSTIFY+ 


1 FNGTH 


LENGTH-CHECK + 


LESS 


UMIT(S) 


LIN+ 


LINAGE 


LINAGE-COUNTER 


LINE 


LINE(S) 


LINE-COUNTER 


LINKAGE 


LOCK 


LOW-VALUE(S) 


MEMORY 


MERGE 


MESSAGE 


MODE 


MODULES 


MOVE 


MULTPLE 


MULTPLY 


NAMES+ 


NATIVE 


NEGATIVE 


NEXT 


NOT 


NUMBER 


NUMBER 


NUMERIC 


OBJECT -COMPUTER 


OCCURS 


OF 


OFF 


OMITTED 


ON 


ON 


OPTIONAL 


OR 


ORGANIZATION 


OUIPUT 


OVLKFLOW 


PAGE 


PAGE-COUNTER 


PEN 


PERFORM 


PF 


PH 


PIC(TURE) 


PLUS 


PLUS 


POINTER 


POSITION 


POSITIVE 


PRINILR+ 


PRINTING 


PROCEDURE(S) 


PROCELU 


PROGRAM 


PROGRAM-ID 


PROMPT+ 


QUEUE 


QUOTE(S) 


RANDOM 


RD 


READ 


READY+ 


RECEIVE 


RECORD(S) 


REDLhiNES 


REEL 


REFERENCES 


RELATIVE 


RELEASE 


REMAINDER 


REMOVAL 


RENAMES 


RLPLACING 


REPORT(S) 


RLHORTING 


RERUN 


RESERVE 


RESET 


RETURN 


REVERSED 


REWIND 


REWRITE 


RF 


RH 


RIGHT 


RIGHT-JUSTIFY+ 


ROUND 


RUN 


SAME 


SCRFFN 


SD 


SEARCH 


SECTION 


SECURE 


SECURITY 


SEGMENT 


SEGMENT-LIMIT 


SELECT 


StlND 


SENTENCE 


StPARATE 


SEQUENCE 


SEQUENTIAL 


SET 


SIGN 


SIZE 


SORT 


SORT-MERGE 


SOURCE 


SOURCE-COMPUTER 


SPACE(S) 


3=ACE-FILL+ 


SPECIAL -NAMES 


STANDARD 


STANDARD- 1 


START 


STATUS 


STOP 


STRING 


SUB-QUEUE-1,2,3 


SUBTRACT 


SUM 


SUPPRESS 


SYMBOLIC 


SYNC(HRONIZED) 


TABLE 


TALLYING 


TAPE 


TERMINAL 


TERMINATE 


TEXT 


THAN 


THROUGH 


THRU 


TTME 


TIMES 


TO 


TOP 


TRACE + 


TRAILING 


TRAILING-SIGN+ 


TYPE 


UNIT 


UNSTRING 


UNTIL 


UP 


UPDATE+ 


UPON 


USAGE 


USE 


USING 


VALUE(S) 


VARYING 


WHEN 


WITH 


WORDS 


WORKING-STORAGE 


WRITE 


ZERO((E)S) 


ZERO-FILL+ 


♦ 


-J*-* 


+ 


- 


/ 

> 


< 
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PERFORM with VARYING and AFTER Clauses 



PERFORM range 

VARYING identifier. 1 FROM amount-1 BY amount-2 
UNTIL condition-1 

AFTER identifier-2 FROM amount-3 BY amount-4 
UNTIL condition-2 



PAFTER identifier-3 FROM amount-5 BY amount-6* 
LL until condition.3 



]J 



Identifier here means a data-name or index-name. Amount-1, -3, and -5 may be 
a data-name, index-name, or literal. Amount-2, -4, and -6 may be a data-name 
or literal only. 

The operation of this complex PERFORM statement is equivalent to the 
following COBOL statements (example varying three items): 

START-PERFORM. 

MOVE amount-1 TO identifier-1 
MOVE amount-3 TO identifier-2 
MOVE amount-5 TO identifier-3. 

TEST-CONDITION-l. 

IF condition-1 GO TO END-PERFORM. 

TEST-C0NDITI0N.2. 
IF condition-2 

MOVE amount-3 TO identifier-2 
ADD amount-2 TO identifier-1 
GO TO TEST-CONDITION-l. 

TEST-CONDITION-3. 
IF Condi tion-3 

MOVE amount-5 TO identifier-3 
ADD amount-4 TO identifier-2 
GO TO TEST.CONDITION-2. 

PERFORM range 

ADD amount-6 TO identifier-3 

GO TO TEST-CONDITION-3, 

END-PERFORM. Next statement. 

NOTE 

If any identifier above were an index-name, the 
associated MOVE would instead be a SET (TO form), 
and the associated ADD would be a SET (UP form). 
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Microsoft COBOL-80 
With Respect to the ANSI Standard 



To understand how COBOL-80 is a 1974 ANSI COBOL, one must know the 
structure of that standard. The COBOL ANSI standard is divided into 12 
"modules": 

I. Nucleus 

2* Table handling 

3, Sequential I/O 

4, Relative I/O 

5, Indexed I/O 

6, Interprogram communication 

7, Library 

a. Communication 

9. Debug 

10. Report-V^iter 

II. Segmentation 

12. Sort/Merge 

Each module has two defined levels of implementation, namely Level I and Level 
II (which is a superset of Level I). According to the standard, the first three 
modules in the list above should be implemented at least to Level I, but the other 
nine modules may or may not be implemented. 
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Referring to the Nucleus and Table Handling modules, Microsoft COBOL-80 
includes all Level II features except: 

I. GENERAL 

L Figurative constant ALL "lit" for literals greater than one character 
2* Qualification of nannes is not allowed in the Environment Division, 

3. Switch testing facility (actually a Level I feature) 

4, Alphabet-name must be "ASCII" and cannot be defined with a literal 
phrase 

n. DATA DIVISION 

1. Occurs depending on ... 

2. Level 88 having list of items intermixed with range (either list or 
range may be used but not both at one time) 

3. COMP data items always require 2 bytes: 

- PICTURE 9(5) only allows a range of -32768 to 32767 

- PICTURES 9,99,999,9999 are equivalent to PIC 9(5) for COMP items 

— Diagnostic is given when more than 5 digits are specified 

4. Unsigned COMP data items 

— PIC 9 is equivalent to PIC S9 

5. Renames phrase 
III. PROCEDURE DIVISION 

1. MOVE, ADD, SUBTRACT CORRESPONDING 

2. Multiple destinations for results of arithmetic statements 

3. Division remainders 

4. Inspect Level II 

5. Arithmetic expressions in conditions 

6. ALTER series of procedure names 
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Regarding the file handling modules, COBOL-80 includes all Level II facilities 
except Multiple Index Keys and special language for TAPE handling, that is: 

1* optional tape file existence by specifying "SELECT OPTIONAL 

filenanne" 

2* buffering of input/output by allowing a fully functional "RESERVE 

Integer AREA(S)" clause 

3. multi-file tapes by specifying the "MULTPLE FILE TAPE 
CONTAINS" clause 

4. control over blocking of fixed and variable-length records by 
allowing fully functional "BLOCK CONTAINS" and "RECORD 
CONTAIN?' clauses in the FD of tape files 

5. multi-reel files, tape reversal, and tape positioning by means of 
fully implemented CLOSE and OPEN statements 

However, the file handling modules do not include the Level I Rerun facility, 
because most microcomputer operating systems have no support for it. 

The Interprogram Communication and Library modules are implemented to Level 
I. 

The Debug and Report-V\friter modules are not implemented at all, and Microsoft 
has no plans for them because they are not very widely used. However, 
COBOL-80 does include the IBM COBOL Debug facility extensions to the ANSI 
standard. 

Another extension Microsoft has incorporated in COBOL-SO is in interactive 
screen control by allowing special options to the ACCEPT and DISPLAY 
statements. Still another extension is the COMP-3 data format which allows 
numeric data to be packed two digits to the byte so that mass storage 
requirements are reduced. 
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INDEX 



Accept 

9, 43, 44, 60, 61, 75 
ACCEPT statement 

9, 60 
ACCESS clause 

19, 103, 109 
ADD statement 

56 
ADVANCING option 

86 
ALL phrase 

91 
Alphanumeric item 

• 22, 27 
Alphanumeric-edited item 

27 
Alter 

80, 116 
ALTER statement 

80 
ANSI level 1 

1, 128 
ANSI level 2 

1, 128 
Arithmetic expression 

58 
Arithmetic statements 

53 
ASCII-entry 

19 
AT END clause 

47, 85, 105, 106, 110 
AUTHOR 

13,17 
Auto 

43-45, 71, 72, 75 
Auto secure 

43 

Bell 

43, 45, 75 
Binary item 

23, 26 
Blank line 

43, 44 
Blank screen 

43, 44 
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Blank vwhen zero 

25, 36, 43-45 
BLANK WHEN ZERO clause 

36 
Blink 

43, 45 
BLOCK clause 

38, 40 

Call 

94, 96 
CALL statennent 

94 
Chain 

95, 96 
Character comparisons 

83 
Character set 

3 
Class test condition 

83 
Close 

2, a, 88, 105, no 

CLOSE statement 

88 
CODE-SET clause 

38, 41 
Column 

43, 44 
Comments 

6, 14, 17 
Compound condition 

81 
COMPUTATIONAL 

23, 25, 26, 98 
COMPUTATIONAL-3 

23, 25, 26 
COMPUTE statement 

58 
Condition 

3, 5, 9, 15, 37, 41, 42, 81, 83, 87, 

91 
Condition-name 

5, 9, 15, 37, 81, 83 
Condition-name test 

83 
Conditional statements 

47, 53 
Conditions 

1 
CONFIGURATION SECTION 

13, 18 
Continuation line 

10, 14 
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Control index 

103 
COUNT IN phrase 

91 
Crt screen formats 

43 
CURRENCY SIGN 

18 

Data description entry 

24,42 
Data Division 

8, U, 13, 22-46 
Data item 

7, 13, 22, 26 
DATA RECORDS clause 

39 
Data-name 

5, 7, 8, 20, 24-26, 34, 35, 39, 41, 

49, 51, 56-58, 60, 83, 86, 96, 97, 

108, 110-112 
DATE-COMPILED 

17 
DATE-WRITTEN 

17 
Debugging 

2, 18 
Decimal item 

25, 36 
Decimal point 

10, 18, 29, 54, 66, 71, 76 
DECIMAL-POINT IS COMMA 

10, 18 
DECLARATIVES 

13, 89, 114-116 
Declaratives 

13, 89, 114-116 
DELETE statement 

108, 112 
DELIMITED BY phrase 

90 
Display 

9, 26, 43-45, 53, 76 
DISPLAY statement 

76 
DIVIDE statement 
57 

Editing 

22, 69, 75 
Elementary item 

7, 22, 25, 26 
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Elementary screen items 

43 
Ellipsis 

6 
Environment Division 

9, 11, 13, 18 
Escape 

60-62, 75 
Escape key 

60-62 
EXHIBIT statement 

93 
EXIT PROGRAM statement 

95 
EXIT statement 

80 
EXTEND phrase 

84 
External decimal item 

23 

FD entry 

8, 14, 38 
Figurative constants 

11 
File 

5, 7, 8, 13, 15, 19, 20, 22, 38, 

84-86, 104 
File name 

5,8 
File Section 

8, 13, 22, 38 
FILE STATUS clause 

20, 104 
FILE STATUS data item 

85 
FILE-CONTROL 

19 
File-name 

5,8 
FILLER 

8, 24 
Fixed segments 

116 
Floating string 

29 
Format notation 

5 
From 

10, 43, 45, 52, 56, 78, 86, 88, 107, 
111, 116 
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General Formats 

5 
GIVING option 

53, 55 
GO TO statement 

59, 80 
Group 

7, 22, 24, 26, 34, 43, 49, 83 
Group item 

• 7, 22, 24, 34, 49 

HIGH- VALUE 

11 
Highlight 

43, 45 

I-O 

19, 84, 89 
1-0 CONTROL paragraph 

19, 21 
I-O error handling 

89 
Identification Division 

11, 13, 17 
IF statement 

81 
Imperative statements 

47 
Independent segments 

X 
Index data-item 

23, 97 
Index-name 

79, 97 
Indexed I-O 

2 
Indexed-file organization 

103 
INPUT file 

84 
INPUT-OUTPUT SECTION 

19 
INSPECT statement 

51 
INSTALLATION 

13, 17 
Inter-Program Communication 

2, 42, 94-96 
Internal decimal item 

23 
INTO option 

85 
INVALID KEY clause 

47, 105-108, 111, 112 
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Just 

14, 43, 45, 107, 110 
Justified 

24, 25, 36, 43, 45 
Justified 

24, 25, 36, 43, 45 
JUSTIRED RIGHT clause 

36 

KEY clause 

100 
KEY IS clause 

106 

LABEL clause 

38 
Level 88 

1, 7, 37, 101 
Level number 

7, a, 14, 22, 24-26, 43, 44 
Level-number 

7, a, 14, 22, 24-26, 43, 44 
Library 

2 
LINAGE clause 

38,41 
Line 

19, 43, 44, 60-62, 69, 89 
Line number 

43, 60-62 
Linkage section 

13, 22, 42, 96 
Literals 

4,9 
LOCK suffix 

88 
LOW- VALUE 

11 

Main program 

96 
Memory 

18, 28, 36, 116 
Memory requirements 

116 
Mnemonic-name 

5, 9, 76 
Modules 

1 
MOVE statement 

49 
MULTIPLY statement 

57 
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Nested IF 

1 
Non-numeric literals 

9 
Nucleus 

1 
Numa*ic comparisons 

83 
Numeric item 

23 
Numeric literals 

10- 

OBJECT-COMPUTER 

18 
OCCURS clause 

24-26, 34 
OMITTED 

38 
ON OVERFLOW clause 

91 
Open 

80, 84, 105 
OPEN statement 

84 
ORGANIZATION clause 

19 
OUTPUT file 

84 
OVERFLOW 

47, 91, 92 
Overlays 

116 

Packed decimal 

23 
Paragraph -name 

13, 48 
Paragraphs 

48 
Parentheses 

1, 6, 58 
Perform 

1, 79, 80, 116 
PERFORM statement 

79 
Pic 

8, 43 
PICTURE 

23-27, 29-32, 35, 43, 45, 50, 83 
Picture 

23-27, 29-32, 35, 43, 45, 50, 33 
PICTURE clause 

24 
Plus 

1, 3, 43, 58, 90, 92 
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POINTER phrase 

90 
PRINTER 

9, 18, 38, 40 
Procedure Division 

11, 13, 47-93, 96, 114 
Procedure division header 

96 
Procedure-name 

14, 48, 59, 80 
PROGRAM-ID 

17 
Punctuation 

3-5 

Qualification 

1,15 
QUOTE 
11 

Range (PERFORM) 

80 
READ statement 

85, 106, 110 
READY TRACE statement 

93 
RECORD CONTAINS clause 

40 
RECORD KEY clause 

104 
Records 

7, 39, 40, 109 
REDEFINES clause 

24-26, 33 
Relative I-O 

2 
Relative indexing 

98 
RELATIVE KEY clause 

110 
RELATIVE KEY item 

110 
Relative organization 

109 
REPLACING clause 

51, 52 
Report item 

22, 25, 28 
RESERVE clause 

20 
Reserved words 

4, 5, 14 
RESET TRACE statement 

92, 93 
REWRITE statement 

88, 107, 111 
ROUNDED option 

53, 55 
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Same 

18, 21 

Screen data description entries 

43 
Screen section 

13, 61, 75, 78 
Screen-name 

43, 61, 75, 76 
SEARCH ALL statement 

100 
SEARCH statement 

99 
Section 

13, 14, 23, 28, 48, 88, 105, 115, 116 
Section header 

116 
Section-name 

13, 48, 116 
Sections 

48, 116, 117 
Secure 

43-45 
SECURITY 

13,17 
Segment 

13, 116 
Segment number 

13, 116 
Segmentation 

2, 116, 117 
SELECT entry 

19, 103, 109, 110 
Sentences 

47, 48 
Separator 

4 
Sequence number 

14 
Sequential I-O 

1 
SET statement 

97 
SIGN clause 

23-25, 28, 36 
Sign test 

1, 83 
Simple condition 

81 
size of data items 

22 
SIZE ERROR option 

47, 54 
SOURCE-COMPUTER 

18 
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SPACE 

11, 53, 63, 70, 71 
SPECIAL-NAMES 

18 
STANDARD 

38, 109 
START statement 

112 
Statements 

47, 54 
STOP statement 

60 
STRING statement 

89 
Subprogram 

96 
Subscripts 

35, 37, 98 
SUBTRACT statement 

56 
SYNCHRONIZED clause 

24-26, 36 

Table Handling 

1, 2, 23, 26, 50, 97-102 
TALLYING clause 

51, 52 
To 

7, 28, 42, 43, 45, 49, 56, 68, 71, 

75, 78, 9Q, 94, 97, 100, 101 
TRACE mode 

92 

UNSTRING statement 

90 
USAGE clause 

24-26 
USE sentence 

13, 114, 115 
Using 

13, 38, 42, 43, 45, 75, 85, 94, 100 
USING list 

42, 94 

Validation 

75 
Value 

2, 24-26, 32, 37-39, 42, 43, 45, 50, 
92, 97, 107 

VALUE IS clause 
32, 42 
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VALUE OF clause 

38, 39 
VARYING 

79, 80, 99, 100 
Verbs 

1,47 

WHEN clause 

100 
Word 

3-5 
Working-storage section 

22, 42 
WRITE statement 

86, 107, 111 



INDEX 



$INCLUDE 2-14 

$MEMRY 4-11 

.COMMENT 2-16 

.CREF 2-23 

.DEPHASE 2-25 

.LALL 2-23 

.LFCOND 2-20 

.LIST 2-20 

.PAGE 2-37 

.PHASE 2-25 

.PRINTX 2-17 

.RADIX 2-6, 2-17 

.REQUEST 2-18 

.SALL 2-23 

.SECOND 2-20 

.TFCOND 2-20 

.XALL 2-23 

.XCREF 2-23 

.XLIST 2-20 

Absolute memory 2-8, 2-11, 2-38 

Arithmetic operators 2-8 

ASEG 2-8, 2-11, 2-24 

Block pseudo ops 2-25 

Character constants 2-7 

Code Relative 2-11, 2-24 to 2-25, 2-38 

Command format 2-1, 3-1, 4-1, 5-1 

Comments 2-6, 2-16 

COMMON 2-8, 2-11, 2-24 to 2-25, 

2-38 to 2-39 

Conditionals 2-19 

Constants 2-6 

CP/M 2-2 to 2-3, 4-4 to 4-6, 

5-1, 5-4 

Cross reference facility . . . 2-4, 2-23, 2-37, 3-1 

CSEG 2-8, 2-11, 2-24, 2-36 

Data Relative 2-8, 2-12, 2-24 to 2-25, 

2-38 

DB 2-6, 2-11 

DC 2-12 

Define Byte 2-6, 2-11 

Define Character 2-12 

Define Origin ■ 2-15 

Define Space 2-12 

Define Word 2-13 

DS 2-12 

DSEG 2-8, 2-12, 2-24, 2-36 

DW 2-13 



EDIT-80 2-5, 2-37 

ELSE 2-20 

END 2-13 

ENDIF 2-20 

ENDM 2-25, 2-29 

ENTRY 2-13, 5-2 

EQU 2-14 to 2-15 

Error codes • 2-35, 2-37 

Error messages 2-36, 4-10 

EXITM 2-29 

EXT 2-14 

Externals 2-9, 2-14, 2-35, 2-38 

EXTEN 2-14 

IF 2-19 

IFl 2-19 

IF2 2-19 

IFB 2-19 

IFDEF 2-19 

IFDIF 2-19 

IFE 2-19 

IFF 2-19 

IFIDN 2-19 

IFNB 2-19 

IFT 2-19 

INCLODE 2-14 

INTEL 2-36 

IRP 2-23, 2-25, 2-27 

IRPC 2-23,-2-25, 2-27 

ISIS-II 2-2 to 2-3, 2-5, 4-5 

LIB-80 5-1 

Library manager 5-1 

LINK-80 2-11, 2-13, 2-18, 2-25, 

4-1, 5-4 

Listings 2-14, 2-20, 2-37 to 2-38, 

3-2, 5-4 

LOCAL 2-30 

Logical operators 2-8 

MACLIB 2-14 

MACRO 2-23, 2-25 to 2-26, 2-28 to 2-29 

Macro operators 2-30 

Modes 2-8 

Modules 5-2 

NAME 2-15 

Operators 2-8 

ORG 2-11, 2-13, 2-15, 2-24 

PAGE 2-15, 2-36 

Program Relative 2-8 

PUBLIC 2-5, 2-13, 2-39 

REPT 2-23, 2-25 to 2-26 

SET 2-15 



strings 2-7 

SUBTTL 2-16, 2-3 6 to 2-37 

Switches 2-3, 3-1, 4-2, 5-3, 5-5 

Symbol table 2-37, 2-39 

TEKDOS 2-1, 3-1, 4-1, A-1 

TITLE 2-15 to 2-16, 2-37 



Did you find errori in the documentation supplied with the 
software? If so, please include page numbers and describe: 



Fill in the following information before returning this form: 
Name Phone 



Organization^ 
Address 



City 



State 



Zip 



Return form to: 



Microsoft 

10800 NE Eighth, Suite 319 

Bellevue, WA 98004 



Microsoft 
Software Problem Report 

Use this form to report errors or problems in: Q FORT3U^-80 

□ COBOL- 80 
n MACRO- 80 

□ LINK- 80 
Release (or version) number: 

Date 

Report only one problem per form. 

Describe your hardware and operating system: 



Please supply a concise description of the problem and the 
circumstances surrounding its occurrence. If possible, reduce 
the problem to a simple test case* Otherwise, include all 
programs and data in machine readable form (preferably on a 
diskette) . If a patch or interim solution is being used, 
please describe it* 

This form may also be used to describe suggested enhancements 
to Microsoft software. 



Problem* Description: 
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ADDENDA TO: Utility Software Manual 

MACRO-80 Assembler Reference Manual 
XMACRO-8 6 Assembler Reference Manual 



The following features were added or modified in release 
3.4. 



Add to Section 2.2.2 Switches 

Switch Action 

/M Initialize Block Data Areas. 

If the programmer wants the area that is defined 
by the DS (Define Space) pseudo-op initialized to 
zeros, then the programmer should use the /M 
switch in the command line. Otherwise, the space 
is not guaranteed to contain zeros. That is, DS 
does not automatically initialize the space to 
zeros. 



/X The presence or absence of /X in the command line 
sets the initial current mode and the initial 
value of the default for listing or suppressing 
lines in false conditional blocks. /X sets the 
current mode and initial value of default to 
not-to-list. No /X sets current mode and initial 
value of default to list. Current mode determines 
whether false conditionals will be listed or 
suppressed. The initial value of the default is 
used with the .TFCOND pseudo-op so that .TFCOND is 
independent of . SFCOND and .LFCOND. If the 
program contains .SFCOND or .LFCOND, /X has no 
effect after .SFCOND or .LFCOND is encountered 
until a .TFCOND is encountered in the file. So /X 
has an effect only when used with a file that 
contains no conditional listing pseudo-ops or when 
used with .TFCOND. 
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The following chart illustrates the effects of the 

three pseudo-ops when encountered under /X and 

under no /X. See the addition to Section 2.6.27 

below for a full description of the three 
conditional listing pseudo-ops- 

PSEUDO-OP ^ Zii /X 
(none) ON OFF 



. SFCOND OFF OFF 



LFCOND ON ON 



, TFCOND OFF ON 



,TFCOND ON OFF 



. SFCOND OFF OFF 



. TFCOND OFF ON 
. TFCOND ON OFF 



.TFCOND OFF ON 

Add to Section 2. 6, 26 Conditional Pseudo Operations 

IFIDN <argl>, <arg2> True if the string <argl> is 

IDeNtical to the string <arg2>* 
The angle brackets around <argl> 
and <arg2> are required. 

IFDIF <argl>, <arg2> True if the string <argl> is 

DIFferent from the string <arg2>. 
The angle brackets around <argl> 
and <arg2> are required. 
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Add to Section 2.6.27 Listing Control Pseudo Operations 

There are now five listing control pseudo-ops. Output to 
the listing file can be controlled by the following 
pseudo-ops : 

.LIST, .XLIST, .SFCOND, .LFCOND, .TFCOND 

The three new pseudo-ops control the listing of conditional 
pseudo-op blocks which evaluate as false. These pseudo-ops 
give the programmer control over four cases. 

1. Normally list false conditionals 

For this case, the programmer simply allows the 
default mode to control the listing. The default 
mode is list false conditionals. If the programmer 
decides to suppress false conditionals, the /X 
switch can be issued in the command line instead of 
editing the source file. 

2. Normally suppress false conditionals 

For this case, the programmer issues the .TFCOND 
pseudo-op in the program file. .TFCOND reverses 
(toggles) the default, causing false conditionals 
to be suppressed. If the programmer decides to 
list false conditionals, the /X switch can be 
issued in the command line instead of editing the 
source file. 

3. Always suppress/list false conditionals 

For these- cases, the program^mer issues either the 

.SFCOND pseudo-op to suppress false conditionals, 

or the .LFCOND pseudo-op to list all false 
conditionals. 

4. Suppress/list some false conditionals 

For this case, the programmer has decided for most 
false conditionals whether to list or suppress, but 
for some false conditionals the programmer has not 
yet decided. For the false conditionals decided 
about, use .SFCOND or .LFCOND. For those not yet 
decided, use .TFCOND. .TFCOND sets the current and 
default settings to the opposite of the default. 
Initially, the default is set by giving /X or no /X 
in the command line. Two subcases exist: 

1. The programmer wants some false conditionals 
not to list unless /X is given. The programmer 
uses the .SFCOND and .LFCOND pseudo-ops to 
control which areas always suppress or list 
false conditionals. To selectively suppress 
some false conditionals, the programmer issues 
.TFCOND at the beginning of the conditional 
block and again at the end of the conditional 
block. (NOTE: The second .TFCOND is should be 
so that the default setting will be the same as 
the initial setting. Leaving the default equal 
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to the initial setting makes it easier to keep 
track of the default mode if there are many 
such areas.) If the conditional block evaluates 
as false, the lines will be suppressed. In 
this subcase, issuing the /X switch in the 
command line causes the conditional block 
affected by .TFCOND to list even if it 
evaluates as false. 

2. The programmer wants some false conditionals to 



list unless /X is given, 
consecutive .TFCONDs places 
listing setting in initial 
determined by the presence or 
switch (the first .TFCOND 
not initial; the second 



of the file. Two 

the conditional 

state which is 

absence of the /X 

sets the default to 

to initial) • The 



selected conditional block then responds to the 
/X switch: if a /X switch is issued in the 
command line, the conditional block is 
suppressed if false; if no /X switch is issued 
in the command line, the conditional block is 
listed even if false. 

The programmer then must reissue the .SFCOND or 
.LFCOND conditional listing pseudo-op to 
restore the suppress or list mode. Simply 
issuing another .TFCOND will not restore the 
prior mode, but will toggle the default 
setting. Since in this subcase, the next area 
of code is supposed to list or suppress false 
conditionals always, the programmer must issue 
.SFCOND or .LFCOND. 



The three conditional listing pseudo-ops are 

below. 



summarized 



PSEUDO-OP 



DEFINITION 



. SFCOND 



Suppresses the listing of 
that evaluate as false. 



conditional blocks 



. LFCOND 



Restores the listing of conditional blocks that 
evaluate as false. 



TFCOND 



Toggles the current setting which controls the 
listing false conditionals. .TFCOND sets the 
current and default setting to not default. If 
a /X switch is given in the MACRO-80 run 
command line for a file which contains .TFCOND, 
/X reverses the effect of .TFCOND. 
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Add to Section 2.7.9 Special Macro Operators and Forms 

The percent sign is used only in a macro argument. 
% converts the expression that follows it (usually a 
symbol) to a number in the current radix. During 
macro expansion, the number derived from converting 
the expression is substituted for the dummy. Using 
the % special operator allows a macro call by value. 
(Usually, a macro call is a call by reference with 
the text of the macro argument substituting exactly 
for the dummy.) 

The expression following the % must conform to the 
same rules as the DS (Define Space) pseudo-op. A 
valid expression returning a non-relocatable 
constant is required. 

EXAMPLE : 

Normally, LB, the argument to MAKLAB, would be 
substituted for Y, the argument to MACRO, as a 
string. The % causes LB to be converted to a 
non-relocatable constant which is then substituted 
for Y. Without the % special operator, the result 
of assembly would be ^Error LB'' rather than ^Error 
1", etc. 



MAKLAB 




MACRO 


y 


ERR&Y : 




DB 
ENDM 


'Error &1?',0 


MAKERR 




MACRO 


X 


LB 




SET 









REPT 


X 


LB 




SET 


LB+1 






MAKLAB 


%LB 






ENDM 








ENDM 




When called 


by MAKERR 3, the 


generate: 








ERRl: 


DB 


"Error 


• l',0 


ERR2: 


DB 


'Error 


• 2',0 


ERR3: 


DB 


'Error 


• 3',0 



assembler will 



CHAPTER 1 
INTRODUCTION 



MACRO-80 is a relocatable macro assembler for 8080 and Z80 
microcomputer systems. It assembles 8080 or Z80 code on any 
8080 or Z80 development system running the CP/Mr ISIS-II, 
TRSDOS or TEKDOS operating system. The MACRO-80 package 
includes the MACRO-80 assembler^ the LINK-80 linking loader ^ 
and the CREF-80 cross reference facility. CP/M versions 
also include the LIB-80 Library Manager. MACRO-80 resides 
in approximately 14K of memory and has an assembly rate of 
over 1000 lines per minute. 



MACRO-80 incorporates almost all "big computer" assembler 
features without sacrificing speed or memory space. The 
assembler supports a complete, Intel standard macro 
facility, including IRP, IRPC, REPEAT, local variables and 
EXITM. Nesting of macros is limited only by memory. Code 
is assembled in relocatable modules that are manipulated 
with the flexible linking loader. Conditional assembly 
capability is enhanced by an expanded set of conditional 
pseudo operations that include testing of assembly pass, 
symbol definition, and parameters to macros. Conditionals 
may be nested up to 255 levels. 



MACRO-80 's linking loader provides a versatile array of 
loader capabilities, which are executed by means of easy 
command lines and switches. Any number of programs may be 
loaded with one command, relocatable modules may be loaded 
in user-specified locations, and external references between 
modules are resolved automatically by the loader. The 
loader also performs library searches for system subroutines 
and generates a load map of memory showing the locations of 
the main program and subroutines. The cross reference 
facility that is included in this package supplies a 
convenient alphabetic list of all program variable names, 
along with the line numbers where they are referenced and 
defined. 
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This manual is designed to serve as a reference guide to the 
MACRO-80 package. It defines, explains and gives examples 
of all the features in MACRO-80 in terms that should be 
understandable to anyone familiar with assembly language 
programming. It is not intended, however, to serve as 
instructional material and presumes the user has substantial 
knowledge of assembly language programming. The user should 
refer to instructional material available from a variety of 
sources for additional tutorial information. 



CHAPTER 2 
MACRO-80 ASSEMBLER 



2.1 RUNNING MACRO-80 

The command to run MACRO-80 is 

M80 

MACRO-80 returns the prompt "*"/ indicating it is ready to 
accept commands. 



NOTE 

If you are using the TEKDOS 
operating system, see Appendix 
A for proper command formats. 



2.2 COMMAND FORMAT 

A command to MACRO-80 consists of a string of filenames with 
optional switches. All filenames should follow the 

operating system's conventions for filenames and extensions. 

The default extensions supplied by Microsoft software are as 
follows: 

File CP/M ISIS-II 

Relocatable object file REL REL 

Listing file PRN LST 

MACRO-80 source file MAC MAC 

FORTRAN source file FOR FOR 

COBOL source COB COB 
Absolute file COM 
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A command to MACRO-80 conveys the name of the source file to 
be assembled, the names of the file(s) to be created, and 
which assembly options are desired. The format of a 
MACRO-80 command is: 

objfile^lstf ile-source file 

Only the equal sign and the source file field are required 
to create a relocatable object file with the default 
(source) filename and the default extension REL. 

Otherwise, an object file is created only if the objfile 
field is filled, and a listing file is created only if the 
Istfile field is filled. 

To assemble the source file without producing an object file 
or listing file, place only a comma to the left of the equal 
sign. This is a handy procedure that lets you check for 
syntax errors before assembling to an object file. 

Examples: 



*=TEST 



Assemble the source file TEST. MAC 

and place the object file in TEST.REL. 



* , =TEST 



Assemble the source file TEST. MAC 
without creating an object or listing 
file. Useful for error checking. 



TEST , TEST=TEST 



Assemble the source file TEST. MAC, 
placing the object file in TEST.REL 
and the listing file in TEST.PRN. 
(With ISIS-II, the listing file is 
TEST.LST.) 



*OBJECT«TEST 



Assemble the source file TEST. MAC 
and place the object file in 
OBJECT. REL. 



OBJECT, LIST=TEST 



Assemble the source file TEST. MAC, 
placing the object file in OBJECT. REL 
and the listing file in LIST.PRN. 
(With ISIS-II, the listing file is 
LIST.LST.) 



MACRO-80 also supports command lines; that is, 
invocation and command may be typed on the same line, 
example: 

M80 ,=TEST 



the 
For 



CP/M 


C:,... 


ISIS-II 


A:, B:, 


:F0:, :P1 


LST: 




LST: 


TTY: 




TTY: 


HSR 







MACRO-80 ASSEMBLER PAGE 2-3 

2.2.1 Devices 

Any field in the MACRO-80 command string can also specify a 
device name. The default device name with the CP/M 
operating system is the currently logged disk. The default 
device name with the ISIS-II operating system is disk drive 
0. The command format is: 

dev:objf ile,dev:lstf ile=dev: source file 

The device names are as follows: 

Device 

Disk drives A:, B:^ C:,... :F0:^ :P1:, :F2:r 
Line printer 
Teletype or CRT 
High speed reader 

Examples: 

*,TTY:=TEST Assemble the source file TEST. MAC 

and list the program on the 
console. No object code is 
generated. Useful for error check. 

*SMALL, TTY: =B: TEST Assemble TEST. MAC (found 

on disk drive B) , place 
the object file in SMALL. REL, 
and list the program on the console. 



2.2.2 Switches 

A switch is a letter that is appended to the command string ^ 
preceded by a slash. It specifies an optional task to be 
performed during assembly. More than one switch can be 
usedr but each must be preceded by a slash. (With the 
TEKDOS operating systemr switches are preceded by commas or 
spaces. See Appendix A.) All switches are optional. The 
available switches are: 

Switch Action 

Octal listing 

H Hexadecimal listing (default) 

R Force generation of an object file 

L Force generation of a listing file 

C Force generation of a cross reference file 
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Z Assemble Z80 opcodes (default for Z80 operating 
systems) 

I Assemble 8080 opcodes (default for 8080 operating 
systems) 

P Each /P allocates an extra 256 bytes of stack 
space for use during assembly. Use /P if stack 
overflow errors occur during assembly. Otherwise, 
not needed. 

M Initialize Block Data Areas. If the programmer 
wants the area that is defined by the DS (Define 
Space) speudo-*op initialized to zeros , then the 
programmer should use the /M switch in the command 
line. Otherwise, the space is not guaranteed to 
contain zeros. That is, DS does not automatically 
initialize the space to zeros. 

X Usually used to suppress the listing of false 
conditionals. The following paragraph describes 
the /X switch more completely but in very 
technical terms. 

The presence or absence of /X in the command line 
sets the initial current mode and the initial 
value of the default for listing or suppressing 
lines in false conditional blocks. /X sets the 
current mode and initial value of default to 
not-to-list. No /X sets current mode and initial 
value of default to list. Current mode determines 
whether false conditionals will be listed or 
suppressed. The initial value of the default is 
used with the .TFCOND pseudo-op so that .TFCOND is 
independent of .SFCOND and .LFCOND. If the 
program contains .SECOND or .LFCOND, /X has no 
effect after .SFCOND or .LFCOND is encountered 
until a .TFCOND is encountered in the file. So /X 
has an effect only when used with a file that 
contains no conditional listing pseudo-ops or when 
used with .TFCOND. 
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Examples: 

*=TEST/L Assemble TEST. MAC, place the object file in 

TEST.REL and a listing file in TEST.PRN. 
(With ISIS-II, the listing file is 
TEST.LST.) 

*=TEST/L/0 Same as above, but listing file addresses 

will be in octal. 

*LAST=TEST/C Assemble TEST. MAC, place the object file in 

LAST.REL and cross reference file in 
TEST.CRF. (See Chapter 3.) 



2.3 FORMAT OF MACRO-80 SOURCE FILES 

Input source lines of up to 132 characters in length are 
acceptable. 

MACRO-80 preserves lower case letters in quoted strings and 
comments. All symbols, opcodes and pseudo-opcodes typed in 
lower case will be converted to upper case. 

If the source file includes line numbers from an editor, 
each byte of the line number must have the high bit on. 
Line numbers from Microsoft's EDIT-80 Editor are acceptable. 



2.3.1 Statements 

Source files input to MACRO-80 consist of statements of the 
form: 

[label: [:]] [operator] [arguments] [;comment] 

With the exception of the ISIS assembler $ controls (see 
Section 2.11), it is not necessary that statements begin in 
column 1. Multiple blanks or tabs may be used to improve 
readability. 

If a label is present, it is the first item in the statement 
and is immediately followed by a colon. If it is followed 
by two colons, it is declared as PUBLIC (see ENTRY/PUBLIC, 
Section 2.6.10). For exmple: 



FOO: : 


RET 


is equivalent 


to 


PUBLIC 


FOO 


FOO: 


RET 
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The next item after the label/ or the first item on the line 
if no label is present, is an operator. An operator may be 
an 8086 mnemonic, pseudo-op, macro call or expression. The 
evaluation order is as follows: 

1, Macro call 

2« Mnemonic/Pseudo operation 

3, Expression 

Instead of flagging an expression as an error, the assembler 
treats it as if it were a DB statement (see Section 2.6.4). 

The arguments following the operator will, of course, vary 
in form according to the operator. 

A comment always begins with a semicolon and ends with a 
carriage return. A comment may be a line by itself or it 
may be appended to a line that contains a statement. 
Extended comments can be entered using the .COMMENT pseudo 
operation (see Section 2.6.20). 



2.3.2 Symbols 

MACRO-aO symbols may be of any length, however, only the 
first six characters are significant. The following 
characters are legal in a symbol: 

A-Z 0-9 $ . ? @ 

With Microsoft' s 8080/Z80/8086 assemblers, the underline 
character is also legal in a symbol. A symbol may not start 
with a digit. When a symbol is read, lower case is 
translated into upper case. If a symbol reference is 
followed by ## it is declared external (see also the 
EXT/EXTRN pseudo-op. Section 2.6.12). 



2.3.3 Numeric Constants 

The default base for numeric constants is decimal. This may 
be changed by the .RADIX pseudo-op (see Section 2.6.22). 
Any base from 2 (binary) to 16 (hexadecimal) may be 
selected. When the base is greater than 10, A-F are the 
digits following 9. If the first digit of the number is not 
numeric the number must be preceded by a zero. 
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Numbers are 16-bit unsigned quantities. A number is always 
evaluated in the current radix unless one of the following 
special notations is used: 



nnnnB 


Binary 


nnnnD 


Decimal 


nnnnO 


Octal 


nnnnQ 


Octal 


nnnnH 


Hexadecimal 


nnnn' 


Hexadecimal 



Overflow of a number beyond two bytes is ignored and the 
result is the low order 16-bits, 

A character constant is a string comprised of zero^ one or 
two ASCII character Sf delimited by quotation marks, and used 
in a non-simple expression. For example, in the statement 

DB 'A' + 1 

'A' is a character constant. But the statement 

DB 'A' 

uses *A* as a string because it is in a simple expression. 
The rules for character constant delimiters are the same as 
for strings. 

A character constant comprised of one character has as its 

value the ASCII value of that character. That is, the high 

order byte of the value is zero, and the low order byte is 

the ASCII value of the character. For example, the value of 
the constant *A' is 41H* 

A character constant comprised of two characters has as its 
value the ASCII value of the first character in the high 
order byte and the ASCII value of the second character in 
the low order byte. For example, the value of the character 
constant "AB" is 41H*256+42H. 



2.3.4 Strings 

A string is comprised of zero or more characters delimited 
by quotation marks. Either single or double quotes may be 
used as string delimiters. The delimiter quotes may be used 
as characters if they appear twice for every character 
occurrence desired. For example, the statement 

DB "I am ""great"" today" 

stores the string 

I am "great" today 
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If there are zero characters between the delimiters, the 
string is a null string. 



2. A EXPRESSION EVALUATION 

2.4.1 Arithmetic And Logical Operators 

The following operators are allowed in expressions. The 
operators are listed in order of precedence. 

NUL 

LOW, HIGH 

*r /, MOD, SHR, SHL 

Unary Minus 

+ r - 

EQ, NE, LT, LE, GT, GE 

NOT 

AND 

ORr XOR 

Parentheses are used to change the order of precedence. 
During evaluation of an expression, as soon as a new 
operator is encountered that has precedence less than or 
equal to the last operator encountered, all operations up to 
the new operator are performed. That is, subexpressions 
involving operators of higher precedence are computed first. 

All operators except +,-,*,/ must be separated from their 
operands by at least one space. 

The byte isolation operators (HIGH, LOW) isolate the high or 
low order 8 bits of an Absolute 16-bit value. If a 
relocatable value is supplied as an operand, HIGH and LOW 
will treat it as if it were relative to location zero. 



2.4.2 Modes 

All symbols used as operands in expressions are in one of 
the following modes: Absolute, Data Relative, Program 
(Code) Relative or COMMON. (See Section 2.6 for the ASEG, 
CSEG, DSEG and COMMON pseudo-ops.) Symbols assembled under 
the ASEG, CSEG (default) , or DSEG pseudo-ops are in 
Absolute, Code Relative or Data Relative mode respectively. 
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The number of COMMON modes in a program is determined by the 
number of COMMON blocks that have been named with the COMMON 
pseudo-op. Two COMMON symbols are not in the same mode 
unless they are in the same COMMON block. In any operation 
other than addition or subtraction r the mode of both 
operands must be Absolute. 

If the operation is addition, the following rules apply: 

1. At least one of the operands must be Absolute. 

2. Absolute + <mode> = <mode> 

If the operation is subtraction, the following rules apply: 

1. <mode> - Absolute = <mode> 

2. <mode> - <mode> = Absolute 

where the two <mode>s are the same. 

Each intermediate step in the evaluation of an expression 
must conform to the above rules for modes, or an error will 
be generated. For example, if FOO, BAZ and ZAZ are three 
Program Relative symbols, the expression 

FOO + BAZ - ZAZ 

will generate an R error because the first step (FOO + BAZ) 
adds two relocatable values. (One of the values must be 
Absolute.) This problem can always be fixed by inserting 
parentheses. So that 

FOO + (BAZ - ZAZ) 

is legal because the first step (BAZ - ZAZ) generates an 
Absolute value that is then added to the Program Relative 
value, FOO. 



2.4.3 Externals 

Aside from its classification by mode, a symbol is either 
External or not External. (See EXT/EXTRN, Section 2.6.12.) 
An External value must be assembled into a two-byte field. 
(Single-byte Externals are not supported.) The following 
rules apply to the use of Externals in expressions: 

1. Externals are legal only in addition and 
subtraction. 

2. If an External symbol is used in an expression, the 
result of the expression is always External. 

3. When the operation is addition, either operand (but 
not both) may be External. 
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4* When the operation is subtraction^ only the first 
operand may be External. 



2.5 OPCODES AS OPERANDS 

8080 opcodes are valid one-byte operands. Note that only 
the first byte is a valid operand. For example: 



MVI 


A, ( JMP) 


ADI 


(CPI) 


MVI 


B, (RNZ) 


CPI 


(INX H) 


ACI 


(LXI B) 


MVI 


CMOV A,B 



Errors will be generated if more than one byte is included 
in the operand — such as (CPI 5) , LXI B^LABELl) or (JMP 
LABEL2) . 

Opcodes used as one-byte operands need not be enclosed in 
parentheses. 



NOTE 

Opcodes are not valid operands 
in Z80 mode. 
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2.6 PSEUDO OPERATIONS 

2.6.1 ASEG 

ASEG 

ASEG sets the location counter to an absolute segment of 
memory. The location of the absolute counter will be that 
of the last ASEG (default is 0) r unless an ORG is done after 
the ASEG to change the location. The effect of ASEG is also 
achieved by using the code segment (CSEG) pseudo operation 
and the /P switch in LINK-80. See also Section 2.6.28 

2.6.2 COMMON 

COMMON /< block name>/ 

COMMON sets the location counter to the selected common 
block in memory. The location is always the beginning of 
the area so that compatibility with the FORTRAN COMMON 
statement is maintained. If <block name> is omitted or 
consists of spaces f it is considered to be blank common. 
See also Section 2.6.28. 

2.6.3 CSEG 

CSEG 

CSEG sets the location counter to the code relative segment 
of memory. The location will be that of the last CSEG 
(default is 0) , unless an ORG is done after the CSEG to 
change the location. CSEG is the default condition of the 
assembler (the INTEL assembler defaults to ASEG) . See also 
Section 2.6.28. 

2.6.4 DB - Define Byte 

DB <exp>[ ,<exp>. . .] 

DB <string> [<string>. . . ] 

The arguments to DB are either expressions or strings. DB 
stores the values of the expressions or the characters of 
the strings in successive memory locations beginning with 
the current location counter. 
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Expressions must evaluate to one byte. (If the high byte of 
the result is or 255, no error is given; otherwise, an A 
error results.) 

Strings of three or more characters may not be used in 
expressions (i.e., they must be immediately followed by a 
comma or the end of the line) . The characters in a string 
are stored in the order of appearance, each as a one-byte 
value with the high order bit set to zero. 

Example: 



0000' 
0002' 
0003' 



41 42 

42 

41 42 43 



DB 
DB 
DB 



'AB' 

'AB' AND OFFH 

•ABC 



2.6.5 DC - Define Character 



DC 



<string> 



DC stores the characters in <string> in successive memory 
locations beginning with the current location counter. As 
with DB, characters are stored in order of appearance, each 
as a one-byte value with the high order bit set to zero. 
However, DC stores the last character of the string with the 
high order bit set to one. An error will result if the 
argument to DC is a null string. 



2.6.6 DS - Define Space 



DS 



<exp> 



DS reserves an area of memory. The value of <exp> gives the 
number of bytes to be allocated. All names used in <exp> 
must be previously defined (i.e., all names known at that 
point on pass 1) . Otherwise, a V error is generated during 
pass 1 and a U error may be generated during pass 2. If a U 
error is not generated during pass 2, a phase error will 
probably be generated because the DS generated no code on 
pass 1. 



2.6.7 DSEG 



DSEG 



DSEG sets the location counter to the Data Relative segment 
of memory. The location of the data relative counter will 
be that of the last DSEG (default is 0) , unless an ORG is 
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done after the DSEG to change the location • See also 
Section 2.6.28. 



2.6.8 DW - Define Word 

DW <exp>[ ,<exp>. . . ] 

DW stores the values of the expressions in successive memory 
locations beginning with the current location counter. 
Expressions are evaluated as 2-byte (word) values. 



2.6.9 END 

END [<exp>] 

The END statement specifies the end of the program. If 
<exp> is present, it is the start address of the program. 
If <exp> is not present/ then no start address is passed to 
LINK-80 for that program. 



NOTE 

If an assembly language 
program is the main program , a 
start address (label) must be 
specified. If not, LINK-80 
will issue a "no start 
address" error. If the 
program is a subroutine to a 
FORTRAN program (for example) / 
the start address is not 
required because FORTRAN has 
supplied one. 



2.6.10 ENTRY/PUBLIC 

ENTRY <name> [ / <name> . . . ] 

or 
PUBLIC <name> [ , <name> . . . ] 

ENTRY or PUBLIC declares each name in the list as internal 
and therefore available for use by this program and other 
programs to be loaded concurrently. All of the names in the 
list must be defined in the current program or a U error 
results. An M error is generated if the name is an external 
name or common-bloc kname. 
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2.6.11 EQU 

<name> EQU <exp> 

EQU assigns the value of <exp> to <name>. If <exp> is 
externals an error is generated. If <name> already has a 
value other than <exp>, an M error is generated. 

2.6.12 EXT/EXTRN 

EXT <name> [ /<naipe>. . . ] 

or 
EXTRN <name> [ ,<naine>. . . ] 

EXT or EXTRN declares that the name(s) in the list are 
external (i.e., defined in a different program). If any 
item in the list references a name that is defined in the 
current programr an M error results. A reference to a name 
where the name is followed immediately by two pound signs 
(e.g.f NAME##) also declares the name as external. 



2.6.13 INCLUDE 

INCLUDE <filename> 

The INCLUDE pseudo-op applies only to CP/M versions of 
MACRO-80. The pseudo-ops INCLUDE, $INCLUDE and MACLIB are 
synonymous. 

The INCLUDE pseudo-op assembles source statements from an 
alternate source file into the current source file. Use of 
INCLUDE eliminates the need to repeat an often-used sequence 
of statements in the current source file. 

<filename> is any valid specification, as determined by the 
operating system. Defaults for filename extensions and 
device names are the same as those in a MACRO-80 command 
line. 

The INCLUDE file is opened and assembled into the current 
source file immediately following the INCLUDE statement. 
When end-of-file is reached, assembly resumes with the 
statement following INCLUDE. 

On a MACRO-80 listing, a plus sign is printed between the 
assembled code and the source line on each line assembled 
from an INCLUDE file. (See Section 2.12.) 

Nested INCLUDES are not allowed. If encountered, they will 
result in an objectionable syntax error '0'. 
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The file specified in the operand field must exist* If the 
file is not found, the error 'V (value error) is given, and 
the INCLUDE is ignored. 



2.6-14 NAME 

NAME ( 'modname') 

NAME defines a name for the module. Only the first six 
characters are significant in a module name. A module name 
may also be defined with the TITLE pseudo-op. In the 
absence of both the NAME and TITLE pseudo-ops, the module 
name is created from the source file name. 



2.6.15 ORG - Define Origin 

ORG <exp> 

The location counter is set to the value of <exp> and the 
assembler assigns generated code starting with that value. 
All names used in <exp> must be known on pass 1, and the 
value must either be absolute or in the same area as the 
location counter. 



2.6.16 PAGE 

PAGE [<exp>] 

PAGE causes the assembler to start a new output page. The 
value of <exp>, if included, becomes the new page size 
(measured in lines per page) and must be in the range 10 to 
255. The default page size is 50 lines per page. The 
assembler puts a form feed character in the listing file at 
the end of a page. 



2.6.17 SET 

<name> SET <exp> 

SET is the same as EQU, except no error is generated if 
<name> is already defined. 
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2.6. 18 SUBTTL 

SUBTTL <text> 

SUBTTL Specifies a subtitle to be listed on the line after 
the title (see TITLE, Section 2.6.19) on each page heading. 
<text> is truncated after 60 characters. Any number of 
SUBTTLs may be given in a program. 

2.6.19 TITLE 

TITLE <text> 

TITLE specifies a title to be listed on the first line of 
each page. If more than one TITLE is given , a Q error 
results. The first six characters of the title are used as 
the module name unless a NAME pseudo operation is used. If 
neither a NAME or TITLE pseudo-op is used, the module name 
is created from the source filename. 



2.6.20 . COMMENT 

.COMMENT <delim><text><delim> 

The first non-blank character encountered after .COMMENT is 
the delimiter. The following <text> comprises a comment 
block which continues until the next occurrence of 
<delimiter> is encountered. For example, using an asterisk 
as the delimiter, the format of the comment block would be: 

. COMMENT * 

any amount of text entered 

here as the comment block 

; return to normal mode 
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2. 6. 21 , PRINTX 

.PRINTX «aelim><text><delim> 

The first non-blank character encountered after .PRINTX is 
the delimiter. The following text is listed on the terminal 
during assembly until another occurrence of the delimiter is 
encountered. .PRINTX is useful for displaying progress 
through a long assembly or for displaying the value of 
conditional assembly switches. For example: 

IF CPM 

•PRINTX /CPM version/ 

ENDIF 



NOTE 

.PRINTX will output on both 
passes. If only one printout 
is desired, use the IFl or IF2 
pseudo-op. For example: 

IF2 

IF CPM 

.PRINTX /CPM version/ 

ENDIF 

ENDIF 



will only print if CPM is true 
and M80 is in pass 2. 



2.6.22 .RADIX 



.RADIX <exp> 



The default base (or radix) for all constants is decimal. 
The .RADIX statement allows the default radix to be changed 
to any base in the range 2 to 16. For example: 

MOVI BX,OFFH 
.RADIX 16 
MOVI BX,OFF 

The two MOVIs in the example are identical. The <exp> in a 
.RADIX statement is always in decimal radix, regardless of 
the current radix. 
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2. 6,23 ,Z80 

.Z80 enables the assembler to accept Z80 opcodes. This is 
the default condition when the assembler is running on a Z80 
operating system. Z80 mode may also be set by appending the 
Z switch to the MACRO-80 command string — see Section 
2.2. 2* 



2.6.24 .8080 

.8080 enables the assembler to accept 8080 opcodes. This is 
the default condition when the assembler is running on an 
8080 operating system. 8080 mode may also be set by 
appending the I switch to the MACRO-80 command string — see 
Section 2.2.2. 



2.6.25 .REQUEST 

.REQUEST <f ilename>[ /<filename>. . . ] 

.REQUEST sends a request to the LINK-80 loader to search the 
filenames in the list for undefined globals. The filenames 
in the list should be in the form of legal symbols. They 
should not include filename extensions or disk 
specifications. LINK-80 supplies a default extension and 
assumes the default disk drive. 
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2,6.26 Conditional Pseudo Operations 
The conditional pseudo operations are; 



IF/IFT <exp> 

IFE/IFF <exp> 

IFl 

IF2 

IFDEF < symbol > 

IFNDEF <syinbol> 
IFB <arg> 

IFNB <arg> 



IFIDN <argl>/<arg2> 



IFDIF <argl>,<arg2> 



True if <exp> is not 0. 

True if <exp> is 0. 

True if pass 1* 

True if pass 2. 

True if <syinbol> is defined or 
has been declared External. 

True if <syinbol> is undefined 
or not declared External. 

True if <arg> is blank. The 
angle brackets around <arg> 
are required. 

True if <arg> is not blank. 
Used for testing when dummy 
parameters are supplied. The 
angle brackets around <arg> 
are required. 

True if the string <argl> is 

IDeNtical to the string 

<arg2>. 

The angle brackets around 

<argl> and <arg2> are 

required. 

True if the string <argl> is 

DIFferent from the string 

<arg2>. 

The angle brackets around 

<argl> and <arg2> are 

required. 



All conditionals use the following format 

IFxx [argument] 

[ELSE 



END IF 
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Conditionals may be nested to any level. Any argument to a 
conditional must be known on pass 1 to avoid V errors and 
incorrect evaluation. For IP, IFT^ IFF, and IFE the 
expression must involve values which were previously defined 
and the expression must be absolute. If the name is defined 
after an IFDEF or IFNDEF, pass 1 considers the name to be 
undefined, but it will be defined on pass 2. 



2.6.26.1 ELSE - Each conditional pseudo operation may 
optionally be used with the ELSE pseudo operation which 
allows alternate code to be generated when the opposite 
condition exists. Only one ELSE is permitted for a given 
IF, and an ELSE is always bound to the most recent, open IF. 
A conditional with more than one ELSE or an ELSE without a 
conditional will cause a C error. 



2.6.26.2 END IF - Each IP must have a matching ENDIP to 
terminate the conditional. Otherwise, an 'Unterminated 
conditional' message is generated at the end of each pass. 
An ENDIP without a matching IF causes a C error. 



2.6.27 Listing Control Pseudo Operations 

Output to the listing file can be controlled by two 
pseudo-ops: 

.LIST and .XLIST 

If a listing is not being made, these pseudo-ops have no 
effect. .LIST is the default condition. When a .XLIST is 
encountered, source and object code will not be listed until 
a .LIST is encountered. 

The output of false conditional blocks is controlled by 
three pseudo-ops: .SECOND, .LPCOND, and .TFCOND. 

These pseudo-ops give the programmer control over four 
cases. 

1. Normally list false conditionals 

For this case, the programmer simply allows the 
default mode to control the listing. The default 
mode is list false conditionals. If the programmer 
decides to suppress false conditionals, the /X 
switch can be issued in the command line instead of 
editing the source file. 
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2. Normally suppress false conditionals 

For this case, the programmer issues the •TFCOND 
pseudo-op in the program file. .TFCOND reverses 
(toggles) the default, causing false conditionals 
to be suppressed. If the programmer decides to 
list false conditionals, the /X switch can be 
issued in the command line instead of editing the 
source file. 

3. Always suppress/list false conditionals 

For these cases, the programmer issues either the 
.SECOND pseudo-op to always suppress false 
conditionals, or the .LFCOND pseudo-op to always 
list all false conditionals. 

4. Suppress/list some false conditionals 

For this case, the programmer has decided for most 
false conditionals whether to list or suppress, but 
for some false conditionals the programmer has not 
yet decided. For the false conditionals decided 
about, use .SFCOND or .LFCOND. For those not yet 
decided, use .TFCOND. .TFCOND sets the current and 
default settings to the opposite of the default. 
Initially, the default is set by giving /X or no /X 
in the command line. Two subcases exist: 

1. The programmer wants some false conditionals 
not to list unless /X is given. The programmer 
uses the .SFCOND and .LFCOND pseudo-ops to 
control which areas always suppress or list 
false conditionals. To selectively suppress 
some false conditionals, the programmer issues 
.TFCOND at the beginning of the conditional 
block and again at the end of the conditional 
block. (NOTE: The second .TFCOND should be 
issued so that the default setting will be the 
same as the initial setting. Leaving the 
default equal to the initial setting makes it 
easier to keep track of the default mode if 
there are many such areas.) If the conditional 
block evaluates as false, the lines will be 
suppressed. In this subcase, issuing the /X 
switch in the command line causes the 
conditional block affected by .TFCOND to list 
even if it evaluates as false. 
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2. The programmer wants some false conditionals to 
list unless /X is given. Two consecutive 
.TFCONDs places the conditional listing setting 
in initial state which is determined by the 
presence or absence of the /X switch in the 
command line (the first .TFCOND sets the 
default to not initial; the second to 
initial) • The selected conditional block then 
responds to the /X switch: if a /X switch is 
issued in the command line, the conditional 
block is suppressed if false; if no /X switch 
is issued in the command line, the conditional 
block is listed even if false. 



The programmer then must 
.LFCOND conditional 1 
restore the suppress or 
issuing another •TFCOND 
prior mode, but will 
setting. Since in this 
of code is supposed to li 
conditionals always, the 
.SFCOND or .LFCOND. 



reissue the .SFCOND or 

isting pseudo-op to 

list mode. Simply 

will not restore the 

toggle the default 

subcase, the next area 

St or suppress false 

programmer must issue 



The three 
below. 



conditional listing pseudo-ops are summarized 



PSEUDO-OP 



DEFINITION 



• SFCOND 
. LFCOND 



Suppresses the listing of conditional 
that evaluate as false. 



blocks 



Restores the listing of conditional blocks that 
evaluate as false. 



. TFCOND 



Toggles the current setting which controls the 
listing false conditionals. .TFCOND sets the 
current and default setting to not default. If 
a /X switch is given in the MACRO-80 run 
command line for a file which contains .TFCOND, 
/X reverses the effect of .TFCOND. 
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The following chart illustrates the effects of the three 
pseudo-ops when encountered under /X and under no /X. 

PSEUDO-OP NO /X /X 

(none) ON OFF 

• • • 

• • • 

• • • 

. SFCOND OFF OFF 

• • • 

• • • 

• • • 

. LFCOND ON ON 

• • • 

• • • 

• • • 

. TFCOND OFF ON 

• • • 

• • • 

• • • 

. TFCOND ON OFF 

• • • 

• • • 

• • • 

. SFCOND OFF OFF 



, TFCOND OFF ON 
, TFCOND ON OFF 



. TFCOND OFF ON 



The output of cross reference information is controlled by 
.CREF and .XCREF. If the cross reference facility {see 
Chapter 3) has not been invoked ^ .CREF and .XCREF have no 
effect. The default condition is .CREF. When a .XCREF is 
encountered^ no cross reference information is output until 
.CREF is encountered. 

The output of MACRO/REPT/IRP/IRPC expansions is controlled 
by three pseudo-ops: .LALL, .SALLr and .XALL. .LALLlists 
the complete macro text for all expansions. .SALL 
suppresses Isiting of all text and object code produced by 
macros. .XALL is the default condition; a source line is 
listed only if it generates object code. 
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2*6.28 Relocation Pseudo Operations 

The ability to create relocatable modules is one of the 
major features of Microsoft assemblers. Relocatable modules 
offer the advantages of easier coding and faster testing, 
debugging and modifying. In addition, it is possible to 
specify segments of assembled code that will later be loaded 
into RAM (the Data Relative segment) and ROM/PROM (the Code 
Relative segment) . The pseudo operations that select 
relocatable areas are CSEG and DSEG. The ASEG pseudo-op is 
used to generate non-relocatable (absolute) code. The 
COMMON pseudo-op creates a common data area for every COMMON 
block that is named in the program. 

The default mode for the assembler is Code Relative. That 
is, assembly begins with a CSEG automatically executed and 
the location counter in the Code Relative mode, pointing to 
location in the Code Relative segment of memory. All 
subsequent instructions will be assembled into the Code 
Relative segment of memory until an ASEG or DSEG or COMMON 
pseudo-op is executed. For example, the first DSEG 
encountered sets the location counter to location zero in 
the Data Relative segment of memory. The following code is 
assembled in the Data Relative mode, that is, it is assigned 
to the Data Relative segment of memory. If a subsequent 
CSEG is encountered, the location counter will return to the 
next free location in the Code Relative segment and so on. 

The ASEG, DSEG, CSEG pseudo-ops never have operands. If you 
wish to alter the current value of the location counter, use 
the ORG pseudo-op. 



2.6.28.1 ORG Pseudo-op - At any time, the value 

of the location counter may be changed by use of the the ORG 

pseudo-op. The form of the ORG statement is: 

ORG <exp> 

where the value of <exp> will be the new value of the 
location counter in the current mode. All names used in 
<exp> must be known on pass 1 and the value of <exp> must be 
either Absolute or in the current mode of the location 
counter. For example, the statements 

DSEG 

ORG 50 

set the Data Relative location counter to 50, relative to 
the start of the Data Relative segment of memory . 
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2.6.28.2 LINK-80 - The LINK-80 linking loader (see 
Chapter 4 of tHTs manual) combines the segments and creates 
each relocatable module in memory when the program is 
loaded. The origins of the relocatable segments are not 
fixed until the program is loaded and the origins are 
assigned by LINK-80. The command to LINK-80 may contain 
user-specif ied origins through the use of the /P (for Code 
Relative) and /D (for Data and COMMON segments) switches. 

For example f a program that begins with the statements 

ASEG 

ORG 800H 

and is assembled entirely in Absolute mode will always load 
beginning at 800 unless the ORG statement is changed in the 
source file. However/ the same program, assembled in Code 
Relative mode with no ORG statement, may be loaded at any 
specified address by appending the /P:<address> switch to 
the LINK-80 command string. 



2.6.29 Relocation Before Loading 

Two pseudo-ops, .PHASE and .DEPHASE, allow code to be 
located in one area, but executed only at a different, 
specified area. 

For example: 

0000' .PHASE lOOH 

0100 E8 0003 FOO: CALL BAZ 
0103 E9 FFOl JMP ZOO 

0106 C3 BAZ: RET 

. DEPHASE 
0007' E9 PFFB ZOO: JMP 5 

All labels within a .PHASE block are defined as the absolute 
value from the origin of the phase area. The code, however, 
is loaded in the current area (i.e., from 0' in this 
example) . The code within the block can later be moved to 
lOOH and executed. 



2.7 MACROS AND BLOCK PSEUDO OPERATIONS 

The macro facilities provided by MACRO-80 include three 
repeat pseudo operations: repeat (REPT) , indefinite repeat 
(IRP) , and indefinite repeat character (IRPC) . A macro 
definition operation (MACRO) is also provided. Each of 
these four macro operations is terminated by the ENDM pseudo 
operation. 
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2.7.1 Terms 

For the purposes of discussion of macros and block 
operations, the following terms will be used: 

1. <dummy> is used to represent a dummy parameter. 
All dummy parameters are legal symbols that appear 
in the body of a macro expansion. 

2. <dummylist> is a list of <dummy>s separated by 
commas • 

3. <arglist> is a list of arguments separated by 
commas. <arglist> must be delimited by angle 
brackets. Two angle brackets with no intervening 
characters {<>) or two commas with no intervening 
characters enter a null argument in the list. 
Otherwise an argument is a character or series of 
characters terminated by a comma or >. With angle 
brackets that are nested inside an <arglist>/ one 
level of brackets is removed each time the 
bracketed argument is used in an <arglist>. See 
example/ Section 2.7.5.) A quoted string is an 
acceptable argument and is passed as such. Unless 
enclosed in brackets or a quoted string , leading 
and trailing spaces are deleted from arguments. 

4. <paramlist> is used to represent a list of actual 
parameters separated by commas. No delimiters are 
required (the list is terminated by the end of line 
or a comment) , but the rules for entering null 
parameters and nesting brackets are the same as 
described for <arglist>. (See example, Section 
2.7.5) 



2.7.2 REPT-ENDM 



REPT <exp> 



ENDM 

The block of statements between REPT and ENDM is repeated 
<exp> times. <exp> is evaluated as a 16-bit unsigned 
number. If <exp> contains any external or undefined terms, 
an error is generated. Example: 

SET 

REPT 10 /-generates DB 1 - DB 10 

SET X+1 

DB X 

ENDM 
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2.7.3 IRP-ENDM 

IRP <duininy> / <arglist> 



ENDM 

The <arglist> must be enclosed in angle brackets. The 
number of arguments in the <arglist> determines the number 
of times the block of statements is repeated. Each 
repetition substitutes the next item in the <arglist> for 
every occurrence of <dummy> in the block. If the <arglist> 
is null (i.e., <>) / the block is processed once with each 
occurrence of <dummy> removed. For example: 

IRP X,<lr2r3,4,5,6,7,8,9,10> 

DB X 

ENDM 

generates the same bytes as the REPT example. 



2.7.4 IRPC-ENDM 



IRPC <dummy>, string (or <string>) 



ENDM 



IRPC is similar to IRP but the arglist is replaced by a 
string of text and- the angle brackets around the string are 
optional. The statements in the block are repeated once for 
each character in the string. Each repetition substitutes 
the next character in the string for every occurrence of 
<dummy> in the block. For example: 

IRPC X, 0123456789 

DB X+1 

ENDM 

generates the same code as the two previous examples. 
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2.7.5 MACRO 

Often it is convenient to be able to generate a given 
sequence of statements from various places in a program, 
even though different parameters may be required each time 
the sequence is used. This capability is provided by the 
MACRO statement. 
The form is 

<name> MACRO <dummylist> 



ENDM 

where <name> conforms to the rules for forming symbols. 
<name> is the name that will be used to invoke the macro. 
The <dummy>s in <dummylist> are the parameters that will be 
changed (replaced) each time the MACRO is invoked. The 
statements before the ENDM comprise the body of the macro. 
During assembly, the macro is expanded every time it is 
invoked but, unlike REPT/IRP/IRPC, the macro is not expanded 
when it is encountered. 

The form of a macro call is 

<name> <paramlist> 

where <name> is the name supplied in the MACRO definition, 
and the parameters in <paramlist> will replace the <dummy>s 
in the MACRO <dummylist> on a one-to-one basis. The number 
of items in <dummylist> and <paramlist> is limited only by 
the length of a line. The number of parameters used when 
the macro is called need not be the same as the number of 
<dummy>s in <dummylist>. If there are more parameters than 
<dummmy>s, the extras are ignored. If there are fewer, the 
extra <dummy>s will be made null. The assembled code will 
contain the macro expansion code after each macro call. 



NOTE 

A dummy parameter in a 
MACRO/REPT/IRP/IRPC is always 
recognized exclusively as a 
dummmy parameter. Register 
names such as A and B will be 
changed in the expansion if 
they were used as dummy 
parameters. 
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Here is an example of a MACRO definition that defines a 
macro called FOO: 



FOO 


MACRO 


X 


Y 


SET 







REPT 


X 


Y 


SET 


Y+1 




DB 

ENDM 

ENDM 


Y 



This macro generates the same code as the previous three 
examples when the call 

FOO 10 

is executed. 

Another example, which generates the same code, illustrates 
the removal of one level of brackets when an argument is 
used as an arglist: 

POO 



MACRO 


X 


IRP 


Y,<X> 


DB 


Y 


ENDM 




ENDM 





When the call 

FOO <1,2,3,4,5,6,7,8,9,10> 

is made, the macro expansion looks like this; 

IRP Y,<1,2,3,4,5,6,7,8,9,10> 

DB Y 

ENDM 



2.7.6 ENDM 

Every REPT, IRP, IRPC and MACRO pseudo-op must be terminated 
with the ENDM pseudo-op. Otherwise, the 'Unterminated 
REPT/IRP/IRPC/MACRO' message is generated at the end of each 
pass. An unmatched ENDM causes an error. 



2.7.7 EXITM 

The EXITM pseudo-op is used to terminate a REPT/IRP/IRPC or 
MACRO call. When an EXITM is executed, the expansion is 
exited immediately and any remaining expansion or repetition 
is not generated. If the block containing the EXITM is 
nested within another block, the outer level continues to be 
expanded. 
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2.7.8 LOCAL 

LOCAL <duminylist> 

The LOCAL pseudo-op is allowed only inside a MACRO 
definition. When LOCAL is executed, the assembler creates a 
unique symbol for each <dummy> in <dummylist> and 
substitutes that symbol for each occurrence of the <dummy> 
in the expansion. These unique symbols are usually used to 
define a label within a macro, thus eliminating 
multiply-defined labels on successive expansions of the 
macro. The symbols created by the assembler range from 
..0001 to ..FFFF. Users will therefore want to avoid the 
form ..nnnn for their own symbols. If LOCAL statements are 
used, they must be the first statements in the macro 
definition. 



2.7.9 Special Macro Operators And Forms 

& The ampersand is used in a macro expansion to 

concatenate text or symbols. A dummy parameter that 
is in a quoted string will not be substituted in the 

expansion unless it is immediately preceded by &. 

To form a symbol from text .and a dummy, put & 
between them. For example: 



ERRGEN MACRO 


X 


ERROR&X:PUSH 


BX 


MOVI 


BX,'&X' 


JMP 


ERROR 


ENDM 





In this example, the call ERRGEN A will generate: 

ERRORA: PUSH B 
MOVI BX , ' A ' 
JMP ERROR 

In a block operation, a comment preceded by two 
semicolons is not saved as part of the expansion 
(i.e., it will not appear on the listing even under 
.LALL) . A comment preceded by one semicolon, 
however, will be preserved and appear in the 
expansion. 

When an exclamation point is used in an argument, 
the next character is entered literally (i.e., !; 
and <;> are equivalent). 
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NUL NUL is an operator that returns true if its argument 
(a parameter) is null. The remainder of a line 
after NUL is considered to be the argument to NUL. 
The conditional 



IF NUL argument 

is false if/ during the expansion, the first 
character of the argument is anything other than a 
semicolon or carriage return. It is recommended 
that testing for null parameters be done using the 
IFB and IFNB conditionals. 

The percent sign is used only in a macro argument. 
% converts the expression that follows it (usually a 
symbol) to a number in the current radix. During 
macro expansion, the number derived from converting 
the expression is substituted for the dummy. Using 
the % special operator allows a macro call by value. 
(Usually, a macro call is a call by reference with 
the text of the macro argument substituting exactly 
for the dummy.) 

The expression following the % must conform to the 
same rules as the DS (Define Space) pseudo-op. A 
valid expression returning a non-relocatable 
constant is required. 

EXAMPLE: Normally, LB, the argument to f^KLAB, 

would be substituted for Y, the argument to MACRO, 

as a string. The % causes LB to be converted to a 
non-relocatable constant which is then substituted 

for Y. Without the % special operator, the result 

of assembly would be 'Error LB' rather than 'Error 
1', etc. 



MAKLAB 


MACRO 


Y 


ERR&Y: 


DB 
ENDM 


'Err 


MAKERR 


MACRO 


X 


LB 


SET 







REPT 


X 


LB 


SET 


LB+1 




MAKLAB 


%LB 




ENDM 






ENDM 





When called by MAKERR 3, the 
generate: 



assembler 



will 



ERRl: 


DB 


'Error 


l',0 


ERR2: 


DB 


'Error 


2\0 


ERR3: 


DB 


'Error 


3',0 
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TYPE The TYPE operator returns a byte that describes two 
characteristics of its argument: 1) the mode, and 
2) whether it is External or not. The argument to 
TYPE may be any expression (string, numeric, 
logical). If the expression is invalid, TYPE 
returns zero. 

The byte that is returned is configured as follows: 

The lower two bits are the mode. If the lower two 
bits are: 

the mode is Absolute 

1 the mode is Program Relative 

2 the mode is Data Relative 

3 the mode is Common Relative 

The high bit (80H) is the External bit. If the high 
bit is on, the expression contains an External. If 
the high bit is off, the expression is local (not 
External) . 

The Defined bit is 20H. This bit is on if the 
expression is locally defined, and it is off if the 
expression is undefined or external. If neither bit 
is on, the expression is invalid. 

TYPE is usually used inside macros, where an 
argument type may need to be tested to make a 
decision regarding program flow. For example: 

FOO MACRO X 
LOCAL Z 
2 SET TYPE X 
IP Z... 
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2.8 USING Z80 PSEUDO-OPS 

When using the MACRO-80 assembler, the following Z80 
pseudo-ops are valid. The function of each pseudo-op is 
equivalent to that of its counterpart. 

Z80 pseudo-op Equivalent pseudo-op 

COND IFT 

ENDC END IP 

♦EJECT PAGE 

DEFB DB 

DEFS DS 

DEFW DW 

DEFM DB 

DEFL SET 

.GLOBAL PUBLIC 

EXTERNAL EXTRN 

The formats, where different, conform to the previous 
format. That is, DEFB and DEFW are permitted a list of 
arguments (as are DB and DW) , and DEFM is permitted a string 
or numeric argument (as is DB) . 
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2.9 SAMPLE ASSEMBLY 



A>M80 














*EXMPL1 , 


,TTY:= 


EXMPLl 










MAC80 


3, 


,2 


PAGE 1 












00100 


;CSL3(P1,P2) 












00200 


; SHIFT Pi LEFT 


CIRCULARLY 3 BITS 










00300 


; RETURN RESULT 


IN P2 










00400 


ENTRY 


CSL3 










00450 


;GET VALUE OF FIRST PARAMETER 










00500 


CSL3: 




0000' 


7E 






00600 


MOV 


A,M 


0001' 


23 






00700 


INX 


H 


0002' 


66 






00800 


MOV 


H,M 


0003' 


6F 






00900 
01000 


MOV 
7 SHIFT COUNT 


L,A 


0004' 


06 


03 




01100 


MVI 


B,3 


0006' 


AF 






01200 
01300 


LOOP : XRA 
; SHIFT LEFT 


A 


0007' 


29 






01400 


DAD 


H 










01500 


; ROTATE IN CY BIT 


0008' 


17 






01600 


RAL 




0009' 


85 






01700 


ADD 


L 


OOOA' 


6F 






01800 


MOV 


L,A 










01900 


; DECREMENT COUNT 


OOOB' 


05 






02000 
02100 


DCR 
;ONE MORE TIME 


B 


OOOC 


C2 


0006' 


02200 


JNZ 


LOOP 


OOOF' 


EB 






02300 


XCHG 












02400 


;SAVE RESULT IN SECOND PARAMETER 


0010' 


73 






02500 


MOV 


M,E 


0011' 


23 






02600 


INX 


H 


0012' 


72 






02700 


MOV 


M,D 


0013' 


C9 


/ 




02800 
02900 


RET 
END 






MAC80 


3. 


,2 


PAGE S 





CSL3 



0000 1' LOOP 



0006 



No Fatal error (s) 
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2.10 MACRO-80 ERRORS 

MACRO-80 errors are indicated by a one-character flag in 
column one of the listing file. If a listing file is not 
being printed on the terminal, each erroneous line is also 
printed or displayed on the terminal. Below is a list of 
the MACRO-80 Error Codes: 

A Argument error 

Argument to pseudo-op is not in correct format or 
is out of range (-PAGE 1; .RADIX 1; PUBLIC 1; 
JMPS TOOFAR) . 

C Conditional nesting error 

ELSE without IF, ENDIF without IF, two ELSEs on 
one IF. 

D Double Defined symbol 

Reference to a symbol which is multiply defined. 

E External error 

Use of an external illegal in context (e.g., FOO 
SET NAME##; MOVI AX, 2-NAME##) . 

M Multiply Defined symbol 

Definition of a symbol which is multiply defined. 

N Number error 

Error in a number, usually a bad digit (e-.g., 8Q) . 

Bad opcode or objectionable syntax 

ENDM, LOCAL outside a block; SET, EQU or MACRO 
without a name; bad syntax in an opcode; or bad 
syntax in an expression (mismatched parenthesis, 
quotes, consecutive operators, etc.). 

P Phase error 

Value of a label or EQU name is different on pass 
2. 

Q Questionable 

Usually means a line is not terminated properly. 
This is a warning error (e.g. MOV AX,BX,). 

R Relocation 

Illegal use of relocation in expression, such as 
abs-rel. Data, code and COMMON areas are 
relocatable. 

U Undefined symbol 

A symbol referenced in an expression is not 
defined. (For certain pseudo-ops, a V error is 
printed on pass 1 and a U on pass 2.) 



MACRO-80 ASSEMBLER PAGE 2-36 



V Value error 

On pass 1 a pseudo-op which must have its value 
known on pass 1 (e.g*, .RADIXf .PAGE, DS, IF, IFE, 
etc. ) f has a value which is undefined. If the 
symbol is defined later in the program, a U error 
will not appear on the pass 2 listing. 



Error Messages: 



'No end statement encountered on input file* 

No END statement: either it is missing or it is 
not parsed due to being in a false conditional, 
unterminated IRP/IRPC/REPT block or terminated 
macro. 

'Unterminated conditional' 

At least one conditional is unterminated at the 
end of the file. 

'Unterminated REPT/IRP/IRPC/MACRO' 

At least one block is unterminated. 

[xx] [No] Fatal error (s) [,xx warnings] 

The number of fatal errors and warnings. The 
message is listed on the CRT and in the list file. 



2.11 COMPATIBILITY WITH OTHER ASSEMBLERS 

The $EJECT and $TITLE controls are provided for 

compatability with INTEL'S ISIS assembler. The dollar sign 

must appear in column 1 only if spaces or tabs separate the 
dollar sign from the control word. The control 

$ EJECT 

is the same as the MACRO-80 PAGE pseudo-op. 
The control 

$TITLE( 'text') 

is the same as the MACRO-80 SUBTTL <text> pseudo-op. 

The INTEL operands PAGE and INPAGE generate Q errors when 
used with the MACRO-80 CSEG or DSEG pseudo-ops. These 
errors are warnings; the assembler ignores the operands. 

When MACRO-80 is entered, the default for the origin is Code 
Relative 0. 

With the INTEL ISIS assembler, the default is Absolute 0. 
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With MACRO-80, the dollar sign {$) is a defined constant 
that indicates the value of the location counter at the 
start of the statement. Other assemblers may use a decimal 
point or an asterisk. Other constants are defined by 
MACRO-80 to have the following values: 



A=7 


B=0 


C=l 


D=2 


E=3 


H=4 


L=5 


M=6 


SP=6 


PSW=6 



2.12 FORMAT OF LISTINGS 

On each page of a MACRO-80 listing, the first two lines have 
the form: 



[TITLE text] 
[SDBTTL text] 



M80 3.3 



PAGE x[-y] 



where: 
1. 

2. 



TITLE text is the text supplied with the TITLE 
pseudo-op f if one was given in the source program. 

X is the major page number, which is incremented 
only when a form feed is encountered in the source 
file. (When using Microsoft's EDIT-80 text editor, 
a form feed is inserted whenever a page mark is 
done.) When the symbol table is being printed, x = 
S. 



3. y is the minor page number, which is incremented 
whenever the .PAGE pseudo-op is encountered in the 
source file, or whenever the current page size has 
been filled. 

4. SDBTTL text is the text supplied with the SUBTTL 
pseudo-op, if one was given in the source program. 

Next, a blank line is printed, followed by the first line of 
output. 

A line of output on a MACRO-80 listing has the following 
form: 



[crf#] 



[error] loc#m 



XX 



xxxx 



source 



If cross reference information is being output, the first 
item on the line is the cross reference number, followed by 
a tab. 



A one-letter error code followed by a space appears next on 
the line, if the line contains an error. If there is no 
error, a space is printed. If there is no cross reference 
number, the error code column is the first column on the 
listing. 
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The value of the location counter appears next on the line. 
It is a 4-digit hexadecimal number or 6-digit octal number, 
depending on whether the /O or /H switch was given in the 
MACRO-80 command string. 

The character at the end of the location counter value is 
the mode indicator. It will be one of the following 
symbols: 

' Code Relative 

" Data Relative 

1 COMMON Relative 

<space> Absolute 

* External 



Next, three spaces are printed followed by the assembled 
code. One-byte values are followed by a space. Two-byte 
values are followed by a mode indicator. Two-byte values 
are printed in the opposite order they are stored in, i.e., 
the high order byte is printed first. Externals are either 
the offset or the value of the pointer to the next External 
in the chain. 

If a line of output on a MACRO-BO listing is from an INCLUDE 
file, the character 'C is printed after the assembled code 
on that line. If a line of output is part of a text 



expansion (MACRO, REPT, IRP, IRPC) a plus 
printed after the assembled code on that line. 



sign '+' is 



The remainder of the line contains the line of source 
as it was input. 

Example: 

0C49 3A A91Z' C+ LDA LCOUNT 



code. 



'C+* indicates this line is from an INCLUDE file and part of 
a macro expansion. 
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2.12.1 Symbol Table Listing 

In the symbol table listing, all the macro names in the 
program are listed alphabetically, followed by all the 
symbols in the program, listed alphabetically. After each 
symbol, a tab is printed, followed by the value of the 
symbol. If the symbol is Public, an I is printed 
immediately after the value. The next character printed 
will be one of the following: 

U Undefined symbol. 

C COMMON block name. (The "value" of the 
COMMON block is its length (number of 
bytes) in hexadecimal or octal.) 

* External symbol. 

<space> Absolute value. 

' Program Relative value. 

" Data Relative value. 

! COMMON Relative value. 



CHAPTER 3 
CREF-80 CROSS REFERENCE FACILITY 



NOTE 

If you are using the TEKDOS 
operating system ^ see Appendix 
A for proper command formats. 



In order to generate a cross reference listing, the 
assembler must output a special listing file with embedded 
control characters. The MACRO-80 command string tells the 
assembler to output this special listing file. /C is the 
cross reference switch. When the /C switch is encountered 
in a MACRO-80 command string, the assembler opens a .CRF 
file instead of a .LST file. (See Section 2.6.27 for the 
.CREF and .XCREF pseudo-ops.) 

Examples: 

*=TEST/C Assemble file TEST.MAC and 

create object file TEST.REL 
and cross reference file 
TEST. CRF. 

*T,U=TEST/C Assemble file TEST. MAC and 

create object file T.REL 
and cross reference file 
U.CRF. 

When the assembler is finished, run the cross reference 
facility by typing CREF80. CREF80 prompts the user with an 
asterisk. CREF80 generates a cross reference listing from 
the .CRF file that was created during assembly. The CREF80 
command format is: 

*listing file=source file 

The default extension for the source file is .CRF. There 
are no switches in CREF80 commands. 
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Examples of CREF-80 command strings: 

*=TEST Examine file TEST.CRF and 

generate a cross reference 
listing file TEST.LST. 

*T=TEST Examine file TEST.CRF and 

generate a cross reference 
listing file T.LST. 

Cross reference listing files differ from ordinary listing 
files in that: 

1. Each source statement is numbered with a cross 
reference number. 

2. At the end of the listing, variable names appear in 
alphabetic order along with the numbers of the 
lines on which they are referenced or defined. 
Line numbers on which the symbol is defined are 
flagged with '#'. 



CHAPTER 4 
LINK-80 LINKING LOADER 



NOTE 

If you are using the TEKDOS 
operating system, see Appendix 
A for proper command formats. 



4.1 RUNNING LINK-80 

The command to run LINK-80 is 

L80 

LINK-80 returns the prompt "**\ indicating it is ready to 
accept commands • 



4.2 COMMAND FORMAT 

Each command to LINK-80 consists of a string of object 
filenames separated by commas. These are the files to be 
loaded by LINK-80. The command format is: 

objf ilelfObjf ile2, . . .objfilen 

The default extension for all filenames is REL. Command 
lines are supported, that is, the invocation and command may 
be typed on the same line. 

Example: 

L80 MYPROCYRPROG 



LINK-80 LINKING LOADER 



PAGE 4-2 



Any filename in the LINK-80 command string can also specify 
a device name. The default device name with the CP/M 
operating system is the currently logged disk. The default 
device with the ISIS-II operating system is disk drive 0. 
The. format is: 

devlrobjf ilelrdev2:objf ile2, . . .devn:objf ilen 
The device names are as listed in Section 2.2.1. 
Example: 

L80 MYPROG,A:YRPROG 

After each line is typed, LINK-80 will load the specified 
files. After LINK finishes this process, it will list all 
symbols that remained undefined followed by an asterisk. 

Example: 

*MAIN 

DATA 0100 0200 

SUBRl* (SUBRl is undefined) 
*SUBR1 

DATA 0100 0300 



Typically, to execute a MACRO-80 program and subroutines, 
the user types the list of filenames followed by /G (begin 
execution) . To resolve any external, undefined symbols, you 
can first search your library routines (See Chapter 5, 
LIB-80) by appending the filenames, followed by /S, to the 
loader command string. 



*MYLIB/S 



VG 



Searches MYLIB.REL for unresolved 
global symbols 

Starts execution 



4.2.1 LINK-80 Switches 

A number of switches may be given in the LINK-80 command 
string to specify actions affecting the loading or execution 
of the program{s). Each switch must be preceded by a slash 
{/) . (With the TEKDOS operating system, switches are 
preceded by hyphens . See Appendix A.) 
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Switches may be placed wherever applicable in the command 
string: 

1. At command level. It is possible for a switch to 
be the entire LINK-80 command, or to appear first 
in the command string. For example: 

*/G Tells LINK-80 to begin execution 

of program (s) already loaded 

*/M List all global references 

from program (s) already loaded 

*/P:200,FOO Load FOO, with program area 
beginning at address 200 

2. Immediately after a filename. An S or N switch may 
refer to only one filename in the command string. 
Therefore r when the S or N switch is required, it 
is placed immediately after that filename, 
regardless of where the filename appears in the 
command string. For example: 

*MYLIB/S,MYPROG 

Search MYLIB.REL and load necessary 
library modules / then load MYPROG.REL. 

*MYPROG/N , MYPROG/E 

Load MYPROG.REL, save MYPROG.'COM 
on disk and exit LINK-SO. 

3. At the end of the command string. Any required 
switches that affect the entire load process may be 
appended at the end of the command string. For 
example : 

*MYPROG/N , MYPROG/M/E 

Open a CP/M COM file called 
MYPR0G.COM, load MYPROG.REL 
and list all global refer- 
ences. Exit LINK-SO and save 
the COM file. 

MYLIB/S , MYSUB , MYPROG/N , MYPROG/M/G 

Search MYLIB.REL^ load and link 

MYSUB. REL and MYPROG.REL, 

open a CP/M COM file 

called MYPR0G.COM, list 

all global references, save the 

COM file, and execute MYPROG. 
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The available switches are: 

Switch Action 

R Reset, Put loader back in its initial state. 

Use /R if you loaded the wrong file by 
mistake and want to restart. /R takes effect 
as • soon as it is encountered in a command 
string. 

E or E:Name Exit LINK-80 and return to the operating 

system. The system library will be searched 
on the current disk to satisfy any existing 
undefined globals. Before exiting, LINK-80 
prints three numbers: the start address, the 
address of the next available byte, and the 
number of 256-byte pages used. The optional 
form E:Name (where Name is a global symbol 
previously defined in one of the modules) 
uses Name for the start address of the 
program. Use /E to load a program and exit 
back to the monitor. 

G or G:Name Start execution of the program as soon as the 

current command line has been interpreted. 
The system library will be searched on the 
current disk to satisfy any existing 
undefined globals if they exist. Before 
execution actually begins, LINK-8'0 prints 
three numbers and a BEGIN EXECUTION message. 
The three numbers are the start address, the 
address of the next available byte, and the 
number of 256-byte pages used. The optional 
form G:Name (where Name is a global symbol 
previously defined in one of the modules) 
uses Name for the start address of the 
program. 

N If a <filename>/N is specified, the program 

will be saved on disk under the selected name 
(with a default extension of .COM for CP/M) 
when a /E or /G is done. A jump to the start 
of the program is inserted if needed so the 
program can run properly (at lOOH for CP/M) . 
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P and D /P and /D allow the origin (s) to be set for 

the next program loaded, /P and /D take 
effect when seen (not deferred) , and they 
have no effect on programs already loaded. 
The form is /P:<address> or /D:<address>, 
where <address> is the desired origin in the 
current typeout radix, (Default radix is 
hex. /O sets radix to octal; /H to hex.) 
LINK-80 does a default /P:<link origin>+3 
(i.e., 103H for CP/M and 4003H for ISIS) to 
leave room for the jump to the start address. 
NOTE: Do not use /P or /D to load programs 
or data into the locations of the loader's 
jump to the start address (lOOH to 102H for 
CP/M) unless it is to load the start of the 
program there. If programs or data are 
loaded into these locations, the jump will 
not be generated. 

If no /D is given, data areas are loaded 
before program areas for each module. If a 
/D is given, all Data and Common areas are 
loaded starting at the data origin and the 
program area at the program origin. Example: 

*/P:200,FOO 

Data 200 300 

*/R 

*/P:200 /D:400,FOO 

Data 400 480 

Program 200 280 

U List the origin and end of the program and 

data area and all undefined globals as soon 
as the current command line has been 
interpreted. The program information is only 
printed if a /D has been done. Otherwise, 
the program is stored in the data area. 

M List the origin and end of the program and 

data area, all defined globals and their 
values, and all undefined globals followed by 
an asterisk. The program information is only 
printed if a /D has been done. Otherwise, 
the program is stored in the data area. 

S Search the filename immediately preceding the 

/S in the command string to satisfy any 
undefined globals. 
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4.2.2 CP/M LINK-80 Switches 

The following switches apply to CP/M versions only. 

X If a filename/N was specified, /X will cause 

the file to be saved in Intel ASCII HEX 
format with an extension of HEX. 

Example: FOO/N/X/E will create an Intel 
ASCII HEX formatted load module named 
FOO.HEX. 

Y If a filename/N was specified , /Y will create 

a filename. SYM file when /E is entered. This 
file contains the names and addresses of all 
Globals for use with Digital Research's 
Symbolic Debugger, SID and ZSID. 

Example: FOO/N/Y/E creates F00.COM and 
FOO.SYM. MYPROG/N/X/Y/E creates MYPROG-HEX 
and MYPROG.SYM. 



4.2.3 Sample Links 

LINK AND GO 

A>L80 

*EXAMPL , EXMPLl/G 
DATA 3000 30AC 
[304F 30AC 49] 
[BEGIN EXECUTION] 



1792 


14336 


14336 


-16383 


-16383 


14 


14 


112 


112 


896 



A> 



LINK AND SAVE 



A>L80 

*EXAMPL , EXAMPLl , EXAM/N/E 
DATA 3000 30AC 
[304F 30AC 49] 
A> 

Loads and links EXAMPL.REL, EXMPLl.REL and creates 
EXAM.COM. 
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4.3 FORMAT OF LINK COMPATIBLE OBJECT FILES 

NOTE 

Section 4.3 is reference 
material for users who wish to 
know the load format of 
LINK-80 relocatable object 
files. Most users will want 
to skip this section^ as it 
does not contain material 
necessary to the operation of 
the package. 

LINK-compatible object files consist of a bit stream. 
Individual fields within the bit stream are not aligned on 
byte boundaries, except as noted below. Use of a bit stream 
for relocatable object files keeps the size of object files 
to a minimum, thereby decreasing the number of disk 
reads/writes. 

There are two basic types of load items: Absolute and 
Relocatable. The first bit of an item indicates one of 
these two types. If the first bit is a 0, the following 8 
bits are loaded as an absolute byte. If the first bit is a 
1, the next 2 bits are used to indicate one of four types of 
relocatable items : 

00 Special LINK item (see below) . 

01 Program Relative. Load the following 16 bits 
after adding the current Program base. 

10 Data Relative. Load the following 16 bits after 
adding the current Data base. 

11 Common Relative. Load the following 16 bits 
after adding the current Common base. 

Special LINK items consist of the bit stream 100 followed 
by: 

a four-bit control field 

an optional A field consisting of a two-bit 
address type that is the same as the two-bit 
field above except 00 specifies absolute address 

an optional B field consisting of 3 bits that 
give a syinbol length and up to 8 bits for each 
character of the symbol 
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A general representation of a special LINK item is: 

1 00 xxxx yy nn zzz + characters of symbol name 

A field B field 

xxxx Four-bit control field (0-15 below) 

yy Two-bit address type field 

nn Sixteen-bit value 

zzz Three-bit symbol length field 

The following special types have a B-field only: 

Entry symbol (name for search) 

1 Select COMMON block 

2 Program name 

3 Request library search 

4 Extension LINK items (see below) 

The following special LINK items have both an A field and a 
B field: 

5 Define COMMON size 

6 Chain external (A is head of address chain, B is 
name of external symbol) 

7 Define entry point (A is address, B is name) 

The following special LINK items have an A field only: 

8 External - offset. Used for JMP and CALL to 
externals 

9 External + offset. The A value will be added to 
the two bytes starting at the current location 
counter immediately before execution. 

10 Define size of Data area (A is size) 

11 Set loading location counter to A 

12 Chain address. A is head of chain, replace all 
entries in chain with current location counter. 
The last entry in the chain has an address field 
of absolute zero. 

13 Define program size (A is size) 

14 End program (forces to byte boundary) 
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The following special Link item has neither an A nor a B 
field: 

15 End file 

An Extension LINK item follows the general format of a 
B-field-only special LINK item^ but contents of the B-field 
are not a symbol name. Instead, the symbol area contains 
one character to identify the type of Extension LINK item, 
followed by from 1 to 7 characters of additional 
information. 

Thus, every Extension LINK item has the format: 

1 00 0100 zzz i jjjjjjj 

where 

zzz may be any three bit integer (with 000 
representing 8) , 

i is an eight bit Extension LINK item type 

identifier, and 



jjjjjjj ^^^ zzz-1 eight bit characters of 
information whose significance depends on i 

At present, there is only one Extension LINK item: 

i = X*35' COBOL overlay segment sentinel 

zzz = 010 (binary) 

j = COBOL segment number -49 (decimal) 

When the overlay segment sentinel is encountered by the 
linker, the current overlay segment number is set to the 
value of j+49. If the previously existing segment 
number was non-zero and a /N switch is in effect, the 
data area is written to disk in a file whose name is the 
current program name and whose extension is Vnn, where 
nn are the two hexadecimal digits representing the 
number j+49 (decimal) • 
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4-4 LINK-80 ERROR MESSAGES 

LINK-80 has the following error messages: 

?No Start Address A /G switch was issued / but no main 

program had been loaded, 

?Loading Error The last file given for input was not a 

properly formatted LINK-80 object file. 

?Out of Memory Not enough memory to load program, 

?Command Error Unrecognizable LINK-80 command, 

?<file> Not Found <file>/ as given in the command string , 

did not exist. 

%2nd COMMON Larger /XXXXXX/ 

The first definition of COMMON block 
/XXXXXX/ was not the largest definition. 
Reorder module loading sequence or 
change COMMON block definitions. 

%Mult. Def. Global YYYYYY 

More than one definition for the global 
(internal) symbol YYYYYY was encountered 
during the loading process. 

%Overlaying f Program! Area , Start = xxxx 

i Data ] , Public = <symbol name>(xxxx) 

/External = <symbol name>(xxxx) 
A /D or /P will cause already loaded 
data to be destroyed. 

?Intersecting ( Program \ Area 
\ Data ) 

The program and data area intersect and 
an address or external chain entry is in 
this intersection. The final value 
cannot be converted to a current value 
since it is in the area intersection. 

?Start Symbol - <name> - Undefined 

After a /E: or /G: is given ^ the 
symbol specified was not defined. 
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Origin 1 Above\ Loader Memory, Move Anyway (Y or N) ? 
\ Below J 

After a /E or /G was given , either the 
data or program area has an origin or 
top which . lies outside loader memory 
(i.e.r loader origin to top of memory). 
If a Y <cr> is given, LINK-80 will move 
the area and continue. If anything else 
is given, LINK-80 will exit. In either 
case, if a /N was given, the image will 
already have been saved. 



?Can't Save Object File 

A disk error occurred when the file 
being saved. 



was 



4.5 PROGRAM BREAK INFORMATION 

LINK-80 stores the address of the first free location in a 
global symbol called $MEMRY if that symbol has been defined 
by a program loaded. $MEMRY is set to the top of the data 
area +1. 



NOTE 



If /D is g 
origin i 
program ar 
sure ther 
keep the 
destroyed, 
particular 
disk dri 
which uses 
disk buffe 



iven and the data 
s less than the 
ea, the user must be 
e is enough room to 
program from being 
This is 
ly true with the 
ver for FORTRAN-80 
$MEMRY to allocate 
r s and FOB ' s . 



CHAPTER 5 
LIB-80 LIBRARY MANAGER 

(CP/M Versions Only) 



LIB-80 is the object time library manager for CP/M versions 
of FORTRAN-80 and COBOL-80, LIB-80 will be interfaced to 
other operating systems in future releases of FORTRAN-80 and 
COBOL-80. 



WARNING 

Read this chapter carefully 
and make a back-up copy of 
your libraries before using 
LIB* It is not difficult to 
destroy a library with LIB-80. 



5.1 LIB-80 COMMANDS 

To run LIB-80 , type LIB followed by a carriage return. 

LIB-80 will return the prompt "*" indicating it is ready to 

accept commands. Each command in LIB-80 either lists 

information about a library or adds new modules to the 
library under construction. 

Commands to LIB-80 consist of an optional destination 
filename which sets the name of the library being created, 
followed by an equal sign, followed by module names 
separated by commas. The default destination filename is 
FORLIB . LIB . Examples : 

*NEWLIB=FILE1 <M0D2>, FILES, TEST 

* S IN , COS , TAN , ATAN 
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Any command specifying a set of modules concatenates the 
modules selected onto the end of the last destination 
filename given. Therefore r 

*FILE1,PILE2 <BIGSDB>, TEST 

is equivalent to 

*FILE1 

*FILE2 <BIGSUB> 

*TEST 



5.I. 1 Modules 

A module is typically a FORTRAN or COBOL subprogram, main 
program or a MACRO-80 assembly that contains ENTRY 
statements. 

The primary function of LIB-80 is to concatenate modules in 
.REL files to form a new library. In order to extract 
modules from previous libraries or .REL files , a powerful 
syntax has been devised to specify ranges of modules within 
a .REL file. 

The simplest way to specify a module within a file is simply 
to use the name of the module. For example: 

SIN 

But a relative quantity plus or minus 255 may also be used. 
For example : 

SIN+1 
specifies the module after SIN and 

SIN-1 

specifies the one before it. 

Ranges of modules may also be specified by using two dots: 

..SIN means all modules up to and including 
SIN. 

SIN. . means all modules from SIN to the end 
of the file. 

SIN.. COS means SIN and COS and all the 
modules in between. 



LIB-80 LIBRARY MANAGER PAGE 5-3 

Ranges of modules and relative offsets may also be used in 
combination: 

SIN+1. .COS-1 

To select a given module from a file^ use the name of the 
file followed by the module (s) specified enclosed in angle 
brackets and separated by commas: 

FORLIB <SIN. .COS> 

or 
MYLIB.REL <TEST> 

or 
BIGLIB.REL <PIRST, MIDDLE, LAST> 

etc. 

If no modules are selected from a file, then all the modules 
in the file are selected: 

TESTLIB.REL 



5.2 LIB-80 SWITCHES 



NOTE 

/E will destroy your current 
library if there is no new 
library under construction. 
Exit LIB-80 using Control-C if 
you are not revising the 
library. 



A number of switches are used to control LIB-80 operation. 
These switches are always preceded by a slash: 

/O Octal - set Octal typeout mode for /L 
command . 



/H Hex - set Hex typeout mode for /L 
command (default) . 

/U List the symbols which would remain 
undefined on a search through the 
file specified. 
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/L List the modules in the files specified 
and symbol definitions they contain. 

/C (Create) Throw away the library under 
construction and start over. 

/E Exit to CP/M. The library under 

construction (.LIB) is revised to .REL 
and any previous copy is deleted. 



NOTE 

/E will destroy your current 
library if there is no new 
library under construction. 
Exit LIB-80 using Control-C if 
you are not revising the 
library. 



/R Rename - same as /E but does not exit 
to CP/M on completion. 



5.3 LIB-80 LISTINGS 

To list the contents of a file in cross reference format, 
use /L: 

*FORLIB/L 

When building libraries r it is important to order the 
modules such that any intermodule references are "forward." 
That is, the module containing the global reference should 
physically appear ahead of the module containing the entry 
point. Otherwise, LINK-80 may not satisfy all global 
references on a single pass through the library. 

Use /U to list the symbols which could be undefined in a 
single pass through a library. If a module in the library 
makes a backward reference to a symbol in another module, /U 
will list that symbol. Example: 

*SYSLIB/U 

NOTE: Since certain modules in the standard FORTRAN and 
COBOL systems are always force-loaded, they will be listed 
as undefined by /U but will not cause a problem when loading 
FORTRAN or COBOL programs. 

Listings are currently always sent to the terminal; use 
control-P to send the listing to the printer. 
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5-4 SAMPLE LIB SESSION 

BUILDING A LIBRARY: 

A>LIB 

*TRANLIB=SIN , COS , TAN , ATAN , ACOG 

*EXP 

*/E 

A> 



LISTING A LIBRARY: 

A>LIB *TRANLIB.LIB/U 
*TRANLIB.LIB/L 



{List of symbols in TRANLIB.LIB) 



*Control-C 

A> 



5.5 SUMMARY OF SWITCHES AND SYNTAX 

/O Octal - set listing radix 

/H Hex - set listing radix 

/U List undefineds 

/L List cross reference 

/C Create - start LIB over 

/E Exit - Rename .LIB to .REL and exit 

/R Rename - Rename .LIB to .REL 



module: :=module name {+ or - number} 

module sequence ::= 

module I ..module | module.. [ modulel. .module2 

file specification: :-f ilename { <module sequence>{ , <module sequence>} } 

command: := {library filename-} {list of file specifications} 
{list of switches} 



APPENDIX A 
TEKDOS Operating System 



The command formats for MACRO-80, LINK-80 and CREF-80 differ 
slightly under the TEKDOS operating system. 



A.l TEKDOS COMMAND FILES 



The files F80, M80, and C80 are actually TEKDOS command 
files for the compiler, assembler, loader, and cross 
reference programs, respectively. These command files set 
the emulation mode to and select the Z-80 assembler 
processor (see TEKDOS documentation) , then execute the 
appropriate program file. You will note that all of these 
command files are set up to execute the Microsoft programs 
from drive 1. LINK-80 will also look for the library 
(FORLIB) on drive 1. If you wish to execute any of this 
software from drive 0, the command file must be edited and 
LINK-80 should be given an explicit library search directive 
"FORLIB-S". (See Section 4.2.1 of this manual.) 



A. 2 MACRO- 80 

The M80 assembler accepts command lines only. A prompt is 
not displayed and interactive commands are not accepted. 
Commands have the same format as TEKDOS assembler commands; 
i.e., three filename or device name parameters plus optional 
switches. 

M80 [objfile] [Istfile] sourcefile [swl] [sw2...] 

The object and listing file parameters are optional. These 
files will not be created if the parameters are omitted, 
however any error messages will still be displayed on the 
console. The available switches are as described in Chapter 
2 of this manual, except that the switches are delimited by 
commas or spaces instead of slashes. 
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A. 3 CREF-80 

The form of commands to CREF80 is: 

C80 Istfile sourcefile 

Both filename parameters are required. The sourcefile 
parameter is always the name of a CREP80 file created during 
assembly, by use of the C switch. 

Example: 

Create a CREP80 file using MACRO-80: 

M80 ,r TSTCRF TSTMAC C 
Create a cross reference listing from the CREP80 file: 

C80 TSTLST TSTCRF 

A. 4 LINK-80 

With TEKDOS, the LINK-80 loader accepts interactive commands 
only. Command lines are not supported. 

When LINK-80 is invoked, and whenever it is waiting for 
input/ it will prompt with an asterisk. Commands *are lists 
of filenames and/or devices separated by commas or spaces 
and optionally interspersed with switches. The input to 
LINK-80 must be Microsoft relocatable object code (not the 
same as TEKDOS loader format) . 

Switches to LINK-80 are delimited by hyphens under TEKDOS ^ 
instead of slashes. All LINK-8 switches (as documented in 
Chapter 3) are supported, except "G" and "N", which are not 
implemented at this time. 

Examples: 

1. Assemble a MACRO-80 program named XTEST, creating 
an object file called XREL and a listing file 
called XLST: 

>M80 XREL XLST XTEST 

2. Load XTEST and save the loaded module: 

>L80 

*XREL-E 

[04AD 22B8] 

*DOS*ERROR 46 

L80 TERMINATED 

>M XMOD 400 22B8 04AD 
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Note that "-E" exits via an error message due to execution 
of a Halt instruction. The memory image is intact, however, 
and the "Module" command may be used to save it. Once a 
program is saved in module format, it may then be executed 
directly without going through LINK-80 again. 

The bracketed numbers printed by LINK-80 before exiting are 
the entry point address and the highest address loaded, 
respectively. The loader default is to begin loading at 
400H. However, the loader also places a jump to the start 
address in location 0, thereby allowing execution to begin 
at 0. The memory locations between 0003 and 0400H are 
reserved for SRB's and I/O buffers at runtime. 
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CHAPTER 1 
INTRODUCTION 



1.1 DESCRIPTION OF THIS MANUAL 



This manual is designed as an introduction to the 
COBOL-language-hosted M/SORT facility and as a reference for 
users. 

The manual is divided into four chapters: 

the first is an introduction to M/SORT — what it is and 
what it does; 

the second is a description of the technical aspects of 
M/SORT — its capabilities and their use in COBOL 
programs; 

the third is two sample programs with discussion of 
program statements unique to M/SORT; 

and the fourth is error status codes — how to invoke 
error code reporting and what the codes mean. 



1.2 DESCRIPTION OF M/SORT 

The following paragraphs introduce M/SORT — what is in the 
package, what is in the facility/ and what are the major 
uses of M/SORT. 



INTRODUCTION Page 1-2 

1.2.1 The M/SORT Distribution Package 

The M/SORT distribution package includes: 

1. A diskette labeled "M/SORT**, compatible with a 
user-specified operating systenif and containing the 
relocatable file SRTLIB and the sample programs and 
data referenced in this documentation. 

2. Documentation; i.e., this manual 



NOTE 

At the time of purchase, you should have 
completed a Non-Disclosure Agreement. If you 
do not remember filling out a Non-Disclosure 
Agreement when you bought this package, look 
in this package for a copy of the Agreement. 
If the Agreement is still in this package, 
remove it, fill it out, and mail it 
immediately. You will be unable to order 
updates to your M/SORT diskette until a copy 
of the Non-Disclosure Agreement is on file 
with Microsoft. 



1.2.2 The M/SORT Facility 



M/SORT is a record sorting facility available to the COBOL 
programmer through 1974 ANSI COBOL SORT/MERGE statements. 

M/SORT accepts input records in an arbitrary order, then 
returns them sequenced according to user specifications. 
The source of the input records may be one or a set of disk 
files; or, records may be constructed in memory by a 
user -writ ten COBOL procedure and RELEASEd to M/SORT one at a 
time. 

Similarly, the sorted output records may be automatically 
written to a disk file; or, records may be left in memory 
for processing by a user-written OUTPUT PROCEDURE within the 
COBOL program. 

M/SORT arranges records in a sequence defined by the 
selection of sort KEYs. The user selects one or more data 
fields of a sort record as the KEYs; the field values are 
compared for record sequencing. 
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Some features of M/SORT require special note: 



1. KEYS - The user specifies on which (ASCENDING 
and/or DESCENDING) KEYs M/SORT sequences records. 
When M/SORT encounters records which are equal in 
terms of all specified KEYs, the records are 
sequenced in the order M/SORT finds them in the 
source files, 

M/SORT supports all data types as KEYs* 

The user may specify up to 12 KEYs, each up to 255 
characters long. 

2. I/O PROCEDURES - If the user elects to use an INPUT 
and /or an OUTPUT PROCEDURE with M/SORT, the user 
must remember that these procedures are performed 
only once for each execution of the SORT statement. 
Looping to read more than one record must be 
included within the INPUT and /or OUTPUT 
PROCEDURE (s) . 



3. SORT STATUS - M/SORT is designed to provide 
comprehensive error reporting in a special SORT 
STATUS register. 

We recommend that every M/SORT program define and 
test a SORT STATUS register. This will facilitate 
error detection and error handling because you will 
know what the error is and approximately where to 
check your program. 



FILE COMPATIBILITY • M/SORT is compatible with all 
COBOL-80 file formats and record lengths. 



5. STANDARD - COBOL-80 with M/SORT conforms fully to 
SORT/MERGEr Level II of the 1974 ANSI COBOL 
standard (except COLLATING SEQUENCE IS 
alphabet-name) . 
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1.2,3 Major Uses For M/SORT 



Most users will have their own sorting requirements which 
will define their uses for M/SORT, 

M/SORT is especially useful for the following jobs: 



1, Providing a pre-sort of records to be loaded into 
an indexed sequential file 

2, Sorting and arranging records to fit a report 
format 

3, Sequencing transactions to be merged into a master 
file 

4, Grouping and arranging items to be displayed in a 
formatted CRT screen layout 



1.3 NECESSARY COMPUTER RESOURCES 



M/SORT is inherently capable of handling files up to 2 
billion bytes in size. Consequently, the speed and power of 
M/SORT in an application is limited only by memory and disk 
space. 



1.3.1 Memory 



M/SORT resides in approximately 6K of memory. To perform a 
very simple and small sorting job, M/SORT requires a minimum 
of 2K of working memory and buffers. Most medium size 
sorting jobs can be handled in 6K-8K of working memory and 
buffers. 

Note that the more working memory M/SORT has available, the 
faster it will run. 
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1.3.2 Disk Space 



Disk requirements for the sort work file vary with record 
length, file size, and the- amount of working memory 
available to M/SORr. With at least 16K bytes of working 
memory available and records no more than 250 bytes long, 
any file up to 100,000 records will require a maximum work 
file of 1*33 times the size of the sorted data. Very small 
sorts with adequate working memory will not use any disk 
space. 



1.4 INSTALLATION OF M/SORT 
Installation of M/SORT is very simple: 



1. Make a back up copy of the M/SORT master and store 
the original in a safe place. 

2. Copy the file SRTLIB onto the disk which will be 
online when you link your COBOL programs. (See the 
COBOL User^s Guide for a discussion of linking.) 

3. The linker will then automatically search SRTLIB 
when needed, just as it will search COBLIB. 

4. Thus, SRTLIB and COBLIB should be on the same disk. 



CHAPTER 2 
COBOL STATEMENT FORMATS 



The SORT-MERGE facility provides the capability to order one 
or more files of records or to combine two or more 
identically ordered files of records/ according to a set of 
user-specified keys contained within each record. 

Optionally r a user may apply some special processing to each 
of the individual records by input or output procedures. 
This special processing may be applied before and/or after 
the records are ordered by the SORT or after the records 
have been combined by the MERGE* 

The following pages illustrate SORT/MERGE syntax , and the 
rules for each statement are specified. 
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2*1 The FILE-CONTROL Paragraph 
The File Control Entry^ 

The file control entry names a sort or merge file. 

2.1*1 Format 

SELECT filename ASSIGN TO DISK 

[SORT STATUS IS identifier] 



2.1.2 Syntax Rules 

1. Each sort or merge file described in the DATA 
DIVISION must be named once and only once as 
filename in the FILE-CONTROL paragraph. Each sort 
or merge file specified in the control entry must 
have a sort-merge file description entry in the 
FILE SECTION of the DATA DIVISION. 

2. For a SELECT sort-filename sentence/ only the 
ASSIGN and STATUS clauses are permitted to follow 
filename in the PILE-CONTROL paragraph. 

3. Identifier must be defined in the WORKING-STORAGE 
SECTION. 



2.1.3 General Rules 



After the execution of any SORT or MERGE statement 
for filename/ the value of identifier will be set 
to a two digit status code. (See Chapter 4 for a 
list of possible values.) Therefore/ identifier 
should be described in the DATA DIVISION as a two 
character field with USAGE DISPLAY. It may be 
defined as numeric. 



COBOL STATEMENT FORMATS 
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2.2 The I-O-CONTROL Paragraph 



The I-O-CONTROL paragraph specifies the memory area which is 

to be shared by different files. (See also COBOL-80 

Reference Manual , Section 2.2.2.2^ for the use of 

I-O-CONTROL entries with non-sort-merge files.) 



2.2.1 Format 



SAME 



RECORD 

SORT ^ AREA FOR filename-l, filename-2 [, filename-3] 

SORT-MERGE 



2.2.2 Syntax Rules 

1. The I-O-CONTROL paragraph is optional. 

2. The SAME SORT AREA and SAME SORT-MERGE AREA clauses 
are equivalent. This compiler will accept the SAME 
SORT AREA and SAME SORT-MERGE AREA clauses without 
giving an error message ^ but they have no effect. 

3. The formats of the SAME clause are considered 
separately in the following: 

a. A filename must not appear in more than one 
SAME RECORD AREA clause. 

b. A filename that represents a sort or merge 
file must not appear in more than one SAME 
SORT AREA or SAME SORT-MERGE AREA clause. 

c. If a filename that does not represent a 
sort or merge file appears in a SAME AREA 
clause and in one or more SAME SORT AREA or 
SAME SORT-MERGE AREA clauses, all files 
named in that SAME AREA clause must be 
named in that SAME SORT AREA or SAME 
SORT-MERGE AREA clause (s). 



4. The files referenced in the SAME RECORD AREA, SAME 
SORT AREA, or SAME SORT-MERGE AREA clause need not 
all have the same organization or access. 
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2* 2. 3 General Rules 



1. The SAME RECORD AREA clause specifies that two or 
more files are to use the same memory area for 
processing of the current logical record. All of 
the files may be open at the same time. A logical 
record in the SAME RECORD AREA is considered as a 
logical record of each opened file whose filename 
appears in this SAME RECORD AREA clause. This is 
equivalent to implicit redefinition of the area; 
i.e./ records are aligned on the leftmost character 
position. 



2. If the SAME SORT AREA or SAME SORT-MERGE AREA 

clause is used/ at least one of the files must 

represent a sort or merge file. Piles that do not 
represent sort or merge files may be named in the 

clause/ and files named in a SAME SORT AREA or SAME 

SORT-MERGE AREA clause may also be named in SAME 
RECORD AREA clause (s) . 
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2.3 DATA DIVISION 

PILE SECTION 

The SORT-MERGE File Description 

An SD file description gives information about the size and 
the names of the data records associated with the file to be 
sorted or merged. 

2.3.1 Format 

SD filename 

[RECORD-clause] 
[DATA-RECORD (s) -clause] 
[VALUE-OF-clause] 



2.3.2 Syntax Rules 

1. The level indicator SD identifies the beginning of 
the sort-merge file description and must precede 
the filename. 

2. The clauses which follow the name of the file are 
optional and their order of appearance is 
immaterial. 

3 . The RECORD-clause , DATA-RECORD ( s) -clause / and 
VALUE-OF-clause are as described in the COBOL-80 
Reference Manual, Section 3.14, "File Section, FD 
Entries". 

4. One or more record description entries must follow 
the sort-merge file description entry. However, no 
input-output statements may be executed for this 
file. 
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2,4 THE SORT STATEMENT 



The SORT Statement 

creates a sort file by executing input procedures or by 
transferring records from one or more USING files; 

sorts the records in the sort file on a set of specified 
keys; 

andf in the final phase of the sort operation, makes 
available each record from the sort file, in sorted 
order/ to an output procedure or to an output file. 



2,4.1 Format 



SORT filename- 



1 ON I 

ri 



ASCENDING I KEY data-name-1 [, data-naine-2] . . . 
DESCENDING f 



ASCENDING 1 KEY data-nanie-3 [, data-name-4 
DESCENDING 



■■■] 



INPUT PROCEDURE IS section-name-1 



through] section-name-2 



[ THRU j 



USING filename-2 [, f ilename-3] . . . 



/OUTPUT PROCEDURE IS section-name--3 



[ THROUGH \ section-name-4 
I THRU I 



GIVING filename-4 



2.4.2 Syntax Rules 

1. Filename-1 must be described in a sort-merge file 
description entry in the DATA DIVISION. 

2. Section-name-1 represents the name of an input 
procedure. Section-name-3 represents the name of 
an output procedure. 
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3. Filename-2, filenaine-3, and filename-4 must be 
described in a file description entry, not in a 
sort-merge file description entry, in the DATA 
DIVISION, Filename-2, filename-3, and filename-4 
may have any type of organization, but ACCESS MODE 
must be sequential. If filename-4 has INDEXED 
organization, the SORT must order records according 
to increasing values of the RECORD KEY, or an error 
will occur during record output. 

4. Data-name-1, data-name-2, data-name-3 , and 
data-name-4 are KEY data-names and are subject to 
the following rules: 

a. The data items identified by KEY data-names 
must be described in records associated 
with filename-1. 

b, KEY data-names may' be qualified, 

c* If filename-1 has more than one record 
description, then the data items identified 
by KEY data-names need be described in only 
one of the record descriptions. 

d. None of the data items identified by KEY 
data-names can be described by an entry 
which either contains an OCCURS clause or 
is subordinate to an entry which contains 
an OCCURS clause. 

e. A maximum of 12 KEY data-names may ' be 
specified. Each KEY data item must be from 
1 to 255 characters in length. 

5. The words THRU and THROUGH are equivalent. 

6. Sort statements may appear anywhere except in the 
declaratives portion of the PROCEDURE DIVISION or 
in an input or output procedure associated with a 
SORT or MERGE statement. 
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2. 4, 3 General Rules 

1, The data-names following the word KEY are listed 
from left to right in the SORT statement in order 
of decreasing significance without regard to how 
they are divided into KEY phrases • In the format, 
data-name-1 is the major key, data-name-2 is the 
next most significant key, etc. 

a* When the ASCENDING phrase is specified, the 
sorted sequence will be from the lowest 
value of the contents of the data items 
identified by the KEY data-names to the 
highest value, according to the rules for 
comparison of operands in a relation 
condition, 

b. When the DESCENDING phrase is specified, 
the sorted sequence will be from the 
highest value of the contents of the data 
items identified by the KEY data-names to 
the lowest value, according to the rules 
for comparison of operands in a relation 
condition. 

c. If the values of the contents of the KEY 
data-names are all the same for two or more 
records, the sorted sequence will be the 
sequence in which the records were RELEASEd 
to the sort by an input procedure, or the 
sequence in which the records existed on a 
USING file. 



2. The input procedure must consist of one or more 
sections that appear contiguously in a source 
program and do not form a part of any output 
procedure. In order to transfer records to the 
file referenced by filename-1, the input procedure 
must include the execution of at least one RELEASE 
statement. Control must not be passed to the input 
procedure, except when a related SORT statement is 
being executed. The input procedure can include 
any procedures needed to select, create, or modify 
records. The restrictions on the procedural 
statements within the input procedure are as 
follows: 

a. The input procedure must not contain any 
SORT or MERGE statements 
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b. The input procedure must not contain any 
explicit transfers of control to points 
outside the input procedure; ALTER ^ GO TO, 
and PERFORM statements in the input 
procedure are not permitted to refer to 
procedure-names outside the input 
procedure. COBOL statements are allowed 
that will cause an implied transfer of 
control to declaratives • 

c* The remainder of the PROCEDURE DIVISION 
must not contain any transfers of control 
to points inside the input procedure; 
ALTER, GO TO, and PERFORM statements in the 
remainder of the PROCEDURE DIVISION must 
not refer to procedure-names within the 
input procedure. 

3. If an input procedure is specified, control is 
passed to the input procedure before filename-1 is 
sequenced by the SORT statement. The compiler 
inserts a return mechanism at the end of the last 
section in the input procedure and when control 
passes the last statement in the input procedure, 
the records that have been released to filename-1 
are sorted. 

4. The output procedure must consist of one or more 
sections that appear continguously in a source 
program and do not form part of any input 
procedure. In order to make sorted records 
available for processing, the output procedure must 
include at least one RETURN statement. Control 
must not be passed to the output procedure, except 
when a related SORT statement is being executed. 
The output procedure may consist of any procedures 
needed to select, modify, or copy the records that 
are being returned, one at a time in sorted order, 
from the sort file. The restrictions on the 
procedural statements within the output procedure 
are as follows: 

a. The output procedure must not contain any 
SORT or MERGE statements. 

b. The output procedure must not contain any 
explicit transfers of control to points 
outside the output procedure; ALTER, GO 
TO, and PERFORM statements in the output 
procedure are not permitted to refer to 
procedure-names outside the output 
procedure. COBOL statements are allowed 
that will cause an implied transfer of 
control to declaratives. 
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The remainder of the PROCEDURE DIVISION 
must not contain any transfers of control 
to points inside the output procedure; 
ALTER r GO TOr and PERFORM statements in the 
remainder of the PROCEDURE DIVISION are not 
permitted to refer to procedure-names 
within the output procedure. 



5. If an output procedure is specified^ control passes 
to it after filename-1 has been sequenced by the 
SORT statement. The compiler inserts a return 
mechanism at the end of the last section in the 
output procedure and when control passes the last 
statement in the output procedure, the return 
mechanism provides for termination of the sort and 
then passes control to the next executable 
statement after the SORT statement. Before 
entering the output procedure , the sort procedure 
reaches a point at which it can select the next 
record in sorted order when requested. The RETURN 
statements in the output procedure are the requests 
for the next record. 

6. Segmentation can be applied to programs containing 
the SORT statement. However , the following 
restrictions apply: 

a. If a SORT statement appears in a section 
that is not in an independent segment, then 
any input procedures or output procedures 
referenced by that SORT statement must 
appear : 

i. Totally within non-independent 
segments, or 

ii. Wholly contained in a single 
independent segment. 

b. If a SORT statement appears in an 
independent segment, then any input 
procedures or output procedures referenced 
by that SORT statement must be contained: 

i. Totally within non-independent 
segments, or 

ii. Wholly within the same independent 
segment as the SORT statement. 
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7. If the USING phrase is specified, all the records 
in filenaine-2 and filename-3 are transferred 
automatically to filename-1. At the time of 
execution of the SORT statement , filename-2 and 
filename-3 must not be open. The SORT statement 
automatically initiates the processing of, makes 
available the logical records for, and terminates 
the processing of filename-2 and filename-3. These 
implicit functions are performed such that any 
associated USE procedures are executed. The 
terminating function for all files is performed as 
if a CLOSE statement*, without optional phrases, had 
been executed for each file. * The SORT statement 
also automatically performs the implicit functions 
of moving records from the area of filename-2 and 
filename-3 to the area for filename-1 and the 
release of records to the initial phase of the sort 
operation. 

8. If the GIVING phrase is specified, all the sorted 
records in filename-1 are automatically written on 
filename-4 as the implied output procedure for this 
SORT statement. At the time of execution of the 
SORT statement filename-4 must not be open. The 
SORT statement automatically initiates the 
processing of, releases the logical records to, and 
terminates the processing of filename-4. These 
implicit functions are performed such that any 
associated USE procedures are executed. The 
terminating function is performed as if a CLOSE 
statement, without optional phrases, had been 
executed for the file. The SORT statement also 
automatically performs the implicit functions of 
the return of the sorted records from the final 
phases of the sort operation and the moving of the 
records from the area for filename-1 to the area 
for filename-4. 
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2.5 THE RELEASE STATEMENT 



The RELEASE statement transfers records to the initial phase 
of a SORT operation. 



2.5.1 Format 

RELEASE record-name [ FROM identifier] 

2.5.2 Syntax Rules 



1. A RELEASE statement may only be used within the 
range of an input procedure associated with a SORT 
statement. 

2. Record-name must be the name of a logical record in 
the associated sort-merge file description entry 
and may be qualified. 



2.5.3 General Rules 

1. The execution of a RELEASE statement causes the 
record named by record-name to be released to the 
initial phase of a sort operation. 

2. If the PROM phrase is used, the contents of the 
indentifier data area are moved to record-name, 
then the contents of record-name are RELEASEd to 
the sort file. Moving takes place according to the 
rules specified for the MOVE statement. After the 
RELEASE statement is executed, the information in 
the record area is no longer available, but the 
information in the data area associated with 
identifier is available. 
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2.6 THE RETURN STATEMENT 



The RETURN statement obtains either sorted records from the 
final phase of a SORT operation or merged records during a 
MERGE operation. 



2.6.1 Format 

RETURN filename RECORD [ INTO identifier] AT END imperative-statement 



2.6.2 Syntax Rules 

1. Filename must be described by a sort-merge file 
description entry in the DATA DIVISION. 

2, A RETURN Statement may only be used within the 
range of an output procedure associated with a SORT 
or MERGE statement for filename. 



2.6.3 General Rules 

1. When the logical records of a file are described 
with more than one record description^ these 
records automatically share the same storage area; 
this is equivalent to an implicit redefinition of 
the area. The contents of any data items which lie 
beyond the range of the current data record are 
undefined at the completion of the execution of the 
RETURN statement. 

2. The execution of the RETURN statement causes the 
next record f in the order specified by the keys 
listed in the SORT or MERGE statement, to be made 
available for processing in the record areas 
associated with the sort or merge file. 
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3. If the INTO phrase is specified^ the current record 
is moved from the input area to the area specified 
by indentifier according to the rules for the MOVE 
statement. The implied MOVE does not occur if 
there is an AT END condition. Any subscripting or 
indexing associated with identifier is evaluated 
after the record has been returned and immediately 
before it is moved to the data item. 

4. When the INTO phrase is used^ the data is available 
in both the input record area and the data area 
associated with identifier. 

5. If no next logical record exists for the file at 
the time of the execution of a RETURN statement ^ 
the AT END condition occurs. The contents of the 
record areas associated with the file when the AT 
END condition occurs are undefined. After the 
execution of the imperative-statement in the AT END 
phrase f no RETURN statement may be executed as part 
of the current output procedure. 
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2.7 THE MERGE STATEMENT 



The MERGE statement combines two or more identically 
sequenced files on a set of specified keys, and during the 
process makes records available, in a . single merged 
sequence, to an output procedure or to an output file. 



2.7.1 Format 



MERGE filename-l ON ( ASCENDING 1 KEY data-name-1 [, data-name-2] 

I DESCENDING j 

'on f ASCENDING ) KEY data-name-3 [, data-name-4] 
I DESCENDING I 



• • i • • 



USING filename-2, filename-3 [ ,f ilename-4] . . . 
OUTPUT PROCEDURE IS section-name-1 



GIVING filename-5 



I THROUGH 1 section-name-2 
I THRU I 



] 



2 •7.2 Syntax Rules 



1. 
2, 
3, 



Filename-l must be described in a sort-merge 
description entry in the DATA DIVISION. 



file 



Section-name-1 represents the 
procedure. 



name of an output 



Pilename-2r filename-3, f ilename-4, and filename-5 
must be described in a file description entry, not 
in a sort-merge file description entry, in the DATA 
DIVISION. Filename-2, filename-3, f ilename-4, and 
filename-5 may have any type of organization, but 
ACCESS MODE must be sequential. If filename-5 has 
INDEXED organization, the SORT must order records 
according to increasing values of the RECORD KEY, 
or an error will occur during record output. 



The words THRU and THROUGH are equivalent. 



CHAPTER 3 
SAMPLE PROGRAMS 



This chapter contains two sample programs and some 
description of details unique to the SORT facility. The 
descriptive passages are intended to help walk you through 
two applications of the facility. 

Before beginning a walk^ through of the sample programs^ two 
points which should be kept in mind throughout coding are: 

1. Your reason for using the SORT facility. 

Also remember: SORT/MERGE is especially useful in 
preparing data for report formats and for loading 
an indexed sequential file; 

2. Input and output procedures are performed only 
oncer rather than repeated for each record. 
Therefore f input and output procedures must include 
a loop to process each record. 
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B>TYPE SAMPLE. OUT 

00011P00800998-001523141 
00011P00801007-000002774 
00224P00800988-000049999 
00077R00801363-000089160 
00145R00801359+000522200 
00077R00801337+000210000 
00077R00801348+000020176 



llOlSd 

120480 
112880 
120580 
120380 
112580 
120180 



B> 



T0T 
103 
103 
201 
201 
202 
203 



ASCENDING MAJOR KEY (SORT-TRANSACTION-CODE) 

•DESCENDING MINOR KEYS (SORT-DATE) 



CHAPTER 4 
ERROR HANDLING 



Microsoft COBOL-80 includes a sp^ecial extension td^I^^ ANSI 
COBOIir the SORT STATUS register • 

The SORT STATUS register makes detection of errors possible. 
At the end of a program run, the SORT STATUS register 
contains a code for any error encountered , or "00" if no 
errors occurred. Error codes specify exactly the type of 
error to help the programmer find the source of the error. 
Consequently^ error handling and debugging are simplified. 

We recommend that every M/SORT program define a SORT STATUS 
item and test it after each SORT or MERGE statement. 

The SORT STATUS IS phrase specifies a data-item in which 
M/SORT should place a status code. 

The SORT STATUS IS phrase is specified in the SELECT 
filename sentence (just as PILE STATUS is specified for a 
non-sort file) . 

The WORKING-STORAGE description of the status data-item 
should specify a two character field with USAGE DISPLAY. 
This item may be numeric. 



